Core Tools is a set of views and perspectives useful for people writing Eclipse
plugins or just wanting to know what is going on under the covers. Roughly speaking
there are three kinds of tools:
- Runtime tools
- The runtime tools expose the internal behaviour of the Platform runtime
as well as certain aspects of plugins (activation ordering, classes loaded,
relation to other plugins, ...) and classes (load order, load nesting, ...).
Plugin developers can use this information to ensure that their plugins/classes
are be activated/loaded as expected, and that they are not taking more time/space
than is warranted.
- Resources tools
- The resources tools expose the behaviour/performance of installed builders
and listeners as well as the structure of the workspace, resources and resource
- Metadata tools
- The metadata tools enable users to investigate the metadata files used to
maintain the resource model. Point these tools at a workspace and browse...
Installing and Running Core Tools
Installing Core Tools
Core Tools comes in two parts; the tools themselves and some patches for the
boot, runtime and resources plugins. To install:
- To install the Core Tools, get org.eclipse.core.tools.zip and extract all
files into the <eclipse install>/plugins directory. This will a add
the Core Tools plugins and fragments to your install.
Use Core Tools version 1.0.0 for Eclipse builds prior to I20030128, and
Core Tools 1.0.1 for all builds after that (including the 2.1 release).
- If you are running an Eclipse build from before I20021127 (this includes
2.0.*) you will need to get the patched versions of the boot, runtime and
resources plugins. Get core-tools-patches.zip and extract all files into your
<eclipse install>/plugins directory. This will overwrite boot.jar, runtime.jar
and resources.jar. Note that if your install has version numbers in the plug-in
directory names, you have to manually copy/extract the patch files into the
corresponding versioned plug-in directory in your install.
Running Core Tools
After installing the Core Tools, you must enable them. The tools are enabled
using Eclipse's debug options mechanism. To run Eclipse in "debug"
mode, use the -debug command line option. If nothing else is said, Eclipse will
look for the file <eclipse install>/.options. This is a Java properties
file detailing which debug options should be enabled etc. See the Eclipse runtime
documentation for more details.
The org.eclipse.core.tools plugin contains an example .options file which enables
all options (except class load trace filters). To run Eclipse with the Core
Tools, either copy this file to your <eclipse install> directory or identify
it on the command line after -debug. For example,
eclipse -debug file:d:/.options
Note that not all tools require enablement. You need only enable the debug
options required by the tools you choose to use. See the tool descriptions for
If you are using PDE's runtime workbench then you can enable tracing and set
the appropriate options for the target workspace. See PDE Guide -> Running
a plug-in -> Running with tracing found in the standard Eclipse documentation
set for more information.
Once you are running with the Core Tools installed, there are a number of new
perspectives and views. These are accessed by opening a new perspective or using
the Window->Show View functions in the workbench.
The runtime tooling contributes a Runtime Spy and Plugin Dependency perspectives.
Note that in some cases the views can be combined or used in other contexts.
The individual views are accessed via the Workspace->Show View->Runtime
Runtime Spy Perspective
The Runtime Spy perspective shows information about the plugin activation,
class loading, resource bundles etc. It is extremely useful when trying to track
down why plugins are being activated or classes loaded as well as getting a
handle on how much code is loaded. This tool contains four views:
- Activated Plugins
- This is the list of plugins which have been activated since the start of
this Eclipse session. Included is total code footprint, startup time, activation
order as well as the number of classes loaded for each plugin.
When plugins are activated a snapshot of the execution stack is taken. This
stack trace can be viewed by selecting plugin and clicking on the stack trace
'T' button on the title bar or in the context menu.
The classes loaded by the selected plugins is shown in the Loaded Classes
view when the "Classes" button ('C') on the menu bar or context
menu is used.
Note that this list is not automatically updated when a new plugin is activated
so users should use the refresh button on the view title bar or in the context
- Loaded Classes
- This view is populated with classes loaded by plugins selected in the Activated
Plugins view. For each class data such as load order and memory footprint
are listed. If the appropriate filtering is enabled when the platform is started
(see below), stack snapshots taken at class loading time are available by
selecting a class and using the Stack Trace menu entry or title bar button.
- Plugin Datasheet
- Shows a summary of the currently selected plugin.
- Stack Trace
- Shows a snapshot of the execution stack at the time of some event (e.g.,
plugin activation, class loading).
The following debug options control what data is available in Runtime Spy perspective
- Whether or not to monitor which classes are loaded.
- Whether or not to monitor which plugins are activated.
- Whether or not to monitor which resource bundles (i.e., *.properties files
) are loaded
- Whether or not to snapshot the execution stack when a class is loaded
- org.eclipse.core.boot/trace/filename=<file location>
- The file in which execution traces are written
- org.eclipse.core.boot/trace/filters=<properties file>
- The location of a Java properties file identifying the classes which should
be traced (if trace/classLoading is true). The File format is:
plugins=<comma separated list of plugins whose classes to trace>
packages=<comma separated list of package prefixes of classes to trace>
Note that there may be many 'plugins' and 'packages' lines in one file.
- Whether or not to snapshot the execution stack when a plugin is activated.
Plug-In Dependency Perspective
This perspective includes 2 views: a plug-in list view listing all the plug-ins
available in the workspace and a plug-in dependency view. The plug-in ids in
the list view are given in alphabetical order (according to their plug-in id).
Select a plug-in in the list view and the dependency view is updated to show
all plug-ins that the selected plug-in requires as well as all plug-ins that
require this selected plug-in. This information is currently only presented
in a text format.
The Resources tooling consists of a number of views described below. These
are accessed via the Workspace->Show View->Resources Tools menu and can
be used independently or together to as desired.
Resource Spy view
This view shows detailed public/internal information about the resource currently
selected in any Eclipse view (e.g. Resource Navigator, Package Explorer, etc).
It shows details about: flags, markers, synchronization information, and session/persistent
Delta Spy View
The Delta Spy listens for any resource changes, echoing the resource delta for
each change event listened. For each affected resource (and its child resources),
it shows the following information:
- the resource's full path;
- the kind of change (between brackets): addition (+), phantom addition (>),
removal (-), phantom removal (<), change (*), no change (~), and unknown
- the change flags (between curly braces): CONTENT, MOVED_FROM, MOVED_TO,
OPEN, TYPE, SYNC, MARKERS, REPLACED, DESCRIPTION;
- in the case it is a marker change, it will show (between brackets) for each
- the kind of marker change: addition (+), removal (-), change (*);
- the marker's id;
- if it is a team private change, a "(team private)" tag.
The Builders/Listeners Spy view displays statistical information about the
behaviour and performance of installed builders and resource change listeners.
The information includes:
- the name of builder/listener (listeners do not technically have names so
their toString() is used)
- the project related to the builder (blank for listeners)
- the number of events (builds or resource changed) processed by the builder/listener
- the amount of time spent processing these events
- the number of core exceptions encountered
For more informatioin on listeners see the Eclipse article "How You've
Changed! Responding to resource changes in the Eclipse workspace" by John
Arthorne (OTI) August 23, 2002. Documentation on builders can be found in the
Platform Plug-in Developer Guide included with the Eclipse documentation.
The following debug options control what data is available in Builder/Listener
- Whether or not to monitor which builders.
- Whether or not to monitor which listeners.
The metadata tooling contributes a Metadata perspective. The individual views
are not particularly useful on their own but are accessed via the Workspace->Show
View->Metadata Tools menu.
The Metadata Perspective
This perspective contains three views which allows the user to select a workspace
metadata directory, browse its structure and see supported files contents and
- Workspace Files Spy
- This view allows the user to select a given workspace .metadata directory
and uses a tree view to show a directory hierarchy (having .metadata as root)
containing all known metadata files as leaf nodes. If the user double-clicks
one of these leaf nodes, the Dump Contents view will be opened having this
file as its current selected file.
- Dump Contents
- This view presents to the user the contents of a selected metadata file
in a human-readable format. It provides an action for selecting a new file
to dump. The contents layout will depend on what kind of file is being dumped.
This view has a sub-view called "Dump Summary" that shows whether
the file read was ok or not.
- Dump Summary
- This view presents to the user the results of a file dumped using the Dump
Contents view. In the case of a error during the dumping process (because
the metadata file being dumped was corrupted), the reason will be shown here,
along with the number of bytes read. This view will only be updated if it
is open when a file is being dumped.
Note: the dumping functionality is also available through a command-line tool:
org.eclipse.core.tools.dumper.DumpTool. To run it, you need to
provide the file to be dumped as an argument. Beware the classpath must include
both Spy and Resources plug-ins' JARs.