Core Tools Readme

## Core Tools

### Introduction

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 deltas.
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:

1. 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).
2. 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 details.

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.

### Runtime Tools

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 Tools menu.

#### 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 menu.
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 views.

org.eclipse.core.boot/monitor/classes=<boolean>
  Whether or not to monitor which classes are loaded.
org.eclipse.core.boot/monitor/plugins=<boolean>
  Whether or not to monitor which plugins are activated.
org.eclipse.core.boot/monitor/bundles=<boolean>
  Whether or not to monitor which resource bundles (i.e., *.properties files ) are loaded
org.eclipse.core.boot/trace/classLoading=<boolean>
  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.
org.eclipse.core.boot/trace/pluginActivation=<boolean>
  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.

### Resources Tools

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 properties.

#### 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 marker changed:
  - the kind of marker change: addition (+), removal (-), change (*);
  - the marker's id;
- if it is a team private change, a "(team private)" tag.

#### Builders/Listeners Spy

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 Spy view.

org.eclipse.core.resources/monitor/builders=<boolean>
  Whether or not to monitor which builders.
org.eclipse.core.resources/monitor/listeners=<boolean>
  Whether or not to monitor which listeners.

### Metadata Tools

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 integrity status.

####

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.

####