platform-core-home/downloads/tools/readme.html
Parent Directory
| 
Revision Log
Revision 1.4 - (view) (download) (as text)
| 1 : | jeff | 1.1 | <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> |
| 2 : | <html> | ||
| 3 : | <head> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 5 : | jeff | 1.3 | <title>Core Tools Readme</title> |
| 6 : | jeff | 1.1 | </head> |
| 7 : | |||
| 8 : | <body> | ||
| 9 : | johna | 1.4 | <h2 align="center">Core Tools</h2> |
| 10 : | jeff | 1.1 | <h3>Introduction</h3> |
| 11 : | |||
| 12 : | |||
| 13 : | <p>Core Tools is a set of views and perspectives useful for people writing Eclipse | ||
| 14 : | plugins or just wanting to know what is going on under the covers. Roughly speaking | ||
| 15 : | there are three kinds of tools:</p> | ||
| 16 : | <dl> | ||
| 17 : | jeff | 1.3 | <dt><b>Runtime tools</b></dt> |
| 18 : | jeff | 1.1 | <dd>The runtime tools expose the internal behaviour of the Platform runtime |
| 19 : | as well as certain aspects of plugins (activation ordering, classes loaded, | ||
| 20 : | relation to other plugins, ...) and classes (load order, load nesting, ...). | ||
| 21 : | Plugin developers can use this information to ensure that their plugins/classes | ||
| 22 : | are be activated/loaded as expected, and that they are not taking more time/space | ||
| 23 : | than is warranted.</dd> | ||
| 24 : | jeff | 1.3 | <dt><b>Resources tools</b></dt> |
| 25 : | jeff | 1.1 | <dd>The resources tools expose the behaviour/performance of installed builders |
| 26 : | and listeners as well as the structure of the workspace, resources and resource | ||
| 27 : | deltas.</dd> | ||
| 28 : | jeff | 1.3 | <dt><b>Metadata tools</b></dt> |
| 29 : | jeff | 1.1 | <dd>The metadata tools enable users to investigate the metadata files used to |
| 30 : | maintain the resource model. Point these tools at a workspace and browse...</dd> | ||
| 31 : | </dl> | ||
| 32 : | |||
| 33 : | |||
| 34 : | <h3>Installing and Running Core Tools</h3> | ||
| 35 : | |||
| 36 : | <h4>Installing Core Tools</h4> | ||
| 37 : | <p>Core Tools comes in two parts; the tools themselves and some patches for the | ||
| 38 : | boot, runtime and resources plugins. To install:</p> | ||
| 39 : | <ol> | ||
| 40 : | <li>To install the Core Tools, get org.eclipse.core.tools.zip and extract all | ||
| 41 : | jeff | 1.3 | files into the <eclipse install>/plugins directory. This will a add |
| 42 : | johna | 1.4 | the Core Tools plugins and fragments to your install. |
| 43 : | Use Core Tools version 1.0.0 for Eclipse builds prior to I20030128, and | ||
| 44 : | Core Tools 1.0.1 for all builds after that (including the 2.1 release).</li> | ||
| 45 : | jeff | 1.2 | <li>If you are running an Eclipse build from before I20021127 (this includes |
| 46 : | jeff | 1.1 | 2.0.*) you will need to get the patched versions of the boot, runtime and |
| 47 : | resources plugins. Get core-tools-patches.zip and extract all files into your | ||
| 48 : | <eclipse install>/plugins directory. This will overwrite boot.jar, runtime.jar | ||
| 49 : | jeff | 1.3 | and resources.jar. Note that if your install has version numbers in the plug-in |
| 50 : | directory names, you have to manually copy/extract the patch files into the | ||
| 51 : | corresponding versioned plug-in directory in your install.</li> | ||
| 52 : | jeff | 1.1 | </ol> |
| 53 : | <h4>Running Core Tools</h4> | ||
| 54 : | <p>After installing the Core Tools, you must enable them. The tools are enabled | ||
| 55 : | using Eclipse's debug options mechanism. To run Eclipse in "debug" | ||
| 56 : | mode, use the -debug command line option. If nothing else is said, Eclipse will | ||
| 57 : | look for the file <eclipse install>/.options. This is a Java properties | ||
| 58 : | file detailing which debug options should be enabled etc. See the Eclipse runtime | ||
| 59 : | documentation for more details. </p> | ||
| 60 : | <p>The org.eclipse.core.tools plugin contains an example .options file which enables | ||
| 61 : | all options (except class load trace filters). To run Eclipse with the Core | ||
| 62 : | Tools, either copy this file to your <eclipse install> directory or identify | ||
| 63 : | it on the command line after -debug. For example, </p> | ||
| 64 : | jeff | 1.2 | <pre> eclipse -debug file:d:/.options</pre> |
| 65 : | jeff | 1.1 | <p>Note that not all tools require enablement. You need only enable the debug |
| 66 : | options required by the tools you choose to use. See the tool descriptions for | ||
| 67 : | details.</p> | ||
| 68 : | <p>If you are using PDE's runtime workbench then you can enable tracing and set | ||
| 69 : | the appropriate options for the target workspace. See PDE Guide -> Running | ||
| 70 : | a plug-in -> Running with tracing found in the standard Eclipse documentation | ||
| 71 : | set for more information.</p> | ||
| 72 : | <p>Once you are running with the Core Tools installed, there are a number of new | ||
| 73 : | perspectives and views. These are accessed by opening a new perspective or using | ||
| 74 : | the Window->Show View functions in the workbench.</p> | ||
| 75 : | <h3>Runtime Tools</h3> | ||
| 76 : | |||
| 77 : | |||
| 78 : | <p>The runtime tooling contributes a Runtime Spy and Plugin Dependency perspectives. | ||
| 79 : | Note that in some cases the views can be combined or used in other contexts. | ||
| 80 : | The individual views are accessed via the Workspace->Show View->Runtime | ||
| 81 : | Tools menu.</p> | ||
| 82 : | <h4>Runtime Spy Perspective</h4> | ||
| 83 : | <p>The Runtime Spy perspective shows information about the plugin activation, | ||
| 84 : | class loading, resource bundles etc. It is extremely useful when trying to track | ||
| 85 : | down why plugins are being activated or classes loaded as well as getting a | ||
| 86 : | handle on how much code is loaded. This tool contains four views: </p> | ||
| 87 : | <dl> | ||
| 88 : | <dt><b>Activated Plugins</b> </dt> | ||
| 89 : | <dd>This is the list of plugins which have been activated since the start of | ||
| 90 : | this Eclipse session. Included is total code footprint, startup time, activation | ||
| 91 : | order as well as the number of classes loaded for each plugin.<br> | ||
| 92 : | When plugins are activated a snapshot of the execution stack is taken. This | ||
| 93 : | stack trace can be viewed by selecting plugin and clicking on the stack trace | ||
| 94 : | 'T' button on the title bar or in the context menu.<br> | ||
| 95 : | The classes loaded by the selected plugins is shown in the Loaded Classes | ||
| 96 : | view when the "Classes" button ('C') on the menu bar or context | ||
| 97 : | menu is used.<br> | ||
| 98 : | Note that this list is not automatically updated when a new plugin is activated | ||
| 99 : | so users should use the refresh button on the view title bar or in the context | ||
| 100 : | menu.</dd> | ||
| 101 : | <dt><b>Loaded Classes</b> </dt> | ||
| 102 : | <dd>This view is populated with classes loaded by plugins selected in the Activated | ||
| 103 : | Plugins view. For each class data such as load order and memory footprint | ||
| 104 : | are listed. If the appropriate filtering is enabled when the platform is started | ||
| 105 : | (see below), stack snapshots taken at class loading time are available by | ||
| 106 : | selecting a class and using the Stack Trace menu entry or title bar button.</dd> | ||
| 107 : | <dt><b>Plugin Datasheet</b> </dt> | ||
| 108 : | <dd>Shows a summary of the currently selected plugin.</dd> | ||
| 109 : | <dt><b>Stack Trace</b> </dt> | ||
| 110 : | <dd>Shows a snapshot of the execution stack at the time of some event (e.g., | ||
| 111 : | plugin activation, class loading).</dd> | ||
| 112 : | </dl> | ||
| 113 : | <p>The following debug options control what data is available in Runtime Spy perspective | ||
| 114 : | views.</p> | ||
| 115 : | <dl> | ||
| 116 : | <dt>org.eclipse.core.boot/monitor/classes=<boolean></dt> | ||
| 117 : | <dd>Whether or not to monitor which classes are loaded.</dd> | ||
| 118 : | <dt>org.eclipse.core.boot/monitor/plugins=<boolean></dt> | ||
| 119 : | <dd>Whether or not to monitor which plugins are activated.</dd> | ||
| 120 : | <dt>org.eclipse.core.boot/monitor/bundles=<boolean></dt> | ||
| 121 : | <dd>Whether or not to monitor which resource bundles (i.e., *.properties files | ||
| 122 : | ) are loaded</dd> | ||
| 123 : | <dt>org.eclipse.core.boot/trace/classLoading=<boolean></dt> | ||
| 124 : | <dd>Whether or not to snapshot the execution stack when a class is loaded</dd> | ||
| 125 : | <dt>org.eclipse.core.boot/trace/filename=<file location></dt> | ||
| 126 : | <dd>The file in which execution traces are written</dd> | ||
| 127 : | <dt>org.eclipse.core.boot/trace/filters=<properties file></dt> | ||
| 128 : | <dd>The location of a Java properties file identifying the classes which should | ||
| 129 : | be traced (if trace/classLoading is true). The File format is: <br> | ||
| 130 : | plugins=<comma separated list of plugins whose classes to trace><br> | ||
| 131 : | packages=<comma separated list of package prefixes of classes to trace><br> | ||
| 132 : | Note that there may be many 'plugins' and 'packages' lines in one file.</dd> | ||
| 133 : | <dt>org.eclipse.core.boot/trace/pluginActivation=<boolean></dt> | ||
| 134 : | <dd>Whether or not to snapshot the execution stack when a plugin is activated.<br> | ||
| 135 : | </dd> | ||
| 136 : | </dl> | ||
| 137 : | <p></p> | ||
| 138 : | <h4>Plug-In Dependency Perspective</h4> | ||
| 139 : | <p>This perspective includes 2 views: a plug-in list view listing all the plug-ins | ||
| 140 : | available in the workspace and a plug-in dependency view. The plug-in ids in | ||
| 141 : | the list view are given in alphabetical order (according to their plug-in id). | ||
| 142 : | Select a plug-in in the list view and the dependency view is updated to show | ||
| 143 : | all plug-ins that the selected plug-in requires as well as all plug-ins that | ||
| 144 : | require this selected plug-in. This information is currently only presented | ||
| 145 : | in a text format.</p> | ||
| 146 : | <h3>Resources Tools</h3> | ||
| 147 : | <p>The Resources tooling consists of a number of views described below. These | ||
| 148 : | are accessed via the Workspace->Show View->Resources Tools menu and can | ||
| 149 : | be used independently or together to as desired. </p> | ||
| 150 : | <h4>Resource Spy view</h4> | ||
| 151 : | This view shows detailed public/internal information about the resource currently | ||
| 152 : | selected in any Eclipse view (e.g. Resource Navigator, Package Explorer, etc). | ||
| 153 : | It shows details about: flags, markers, synchronization information, and session/persistent | ||
| 154 : | properties. | ||
| 155 : | <h4>Delta Spy View</h4> | ||
| 156 : | The Delta Spy listens for any resource changes, echoing the resource delta for | ||
| 157 : | each change event listened. For each affected resource (and its child resources), | ||
| 158 : | it shows the following information: | ||
| 159 : | <ul> | ||
| 160 : | <li>the resource's full path;</li> | ||
| 161 : | <li>the kind of change (between brackets): addition (+), phantom addition (>), | ||
| 162 : | removal (-), phantom removal (<), change (*), no change (~), and unknown | ||
| 163 : | (?);</li> | ||
| 164 : | <li>the change flags (between curly braces): CONTENT, MOVED_FROM, MOVED_TO, | ||
| 165 : | OPEN, TYPE, SYNC, MARKERS, REPLACED, DESCRIPTION;</li> | ||
| 166 : | <li>in the case it is a marker change, it will show (between brackets) for each | ||
| 167 : | marker changed: | ||
| 168 : | <ul> | ||
| 169 : | <li>the kind of marker change: addition (+), removal (-), change (*);</li> | ||
| 170 : | <li>the marker's id;</li> | ||
| 171 : | </ul> | ||
| 172 : | </li> | ||
| 173 : | <li>if it is a team private change, a "(team private)" tag.</li> | ||
| 174 : | </ul> | ||
| 175 : | <h4>Builders/Listeners Spy</h4> | ||
| 176 : | <p>The Builders/Listeners Spy view displays statistical information about the | ||
| 177 : | behaviour and performance of installed builders and resource change listeners. | ||
| 178 : | The information includes:</p> | ||
| 179 : | <ul> | ||
| 180 : | <li>the name of builder/listener (listeners do not technically have names so | ||
| 181 : | their toString() is used)</li> | ||
| 182 : | <li>the project related to the builder (blank for listeners)</li> | ||
| 183 : | <li>the number of events (builds or resource changed) processed by the builder/listener</li> | ||
| 184 : | <li>the amount of time spent processing these events</li> | ||
| 185 : | <li>the number of core exceptions encountered</li> | ||
| 186 : | </ul> | ||
| 187 : | <p>For more informatioin on listeners see the Eclipse article "How You've | ||
| 188 : | Changed! Responding to resource changes in the Eclipse workspace" by John | ||
| 189 : | Arthorne (OTI) August 23, 2002. Documentation on builders can be found in the | ||
| 190 : | Platform Plug-in Developer Guide included with the Eclipse documentation.</p> | ||
| 191 : | <p>The following debug options control what data is available in Builder/Listener | ||
| 192 : | Spy view.</p> | ||
| 193 : | <dl> | ||
| 194 : | <dt>org.eclipse.core.resources/monitor/builders=<boolean></dt> | ||
| 195 : | <dd>Whether or not to monitor which builders.</dd> | ||
| 196 : | <dt>org.eclipse.core.resources/monitor/listeners=<boolean></dt> | ||
| 197 : | <dd>Whether or not to monitor which listeners.</dd> | ||
| 198 : | </dl> | ||
| 199 : | |||
| 200 : | <h3>Metadata Tools</h3> | ||
| 201 : | <p>The metadata tooling contributes a Metadata perspective. The individual views | ||
| 202 : | are not particularly useful on their own but are accessed via the Workspace->Show | ||
| 203 : | View->Metadata Tools menu.</p> | ||
| 204 : | <h4></h4> | ||
| 205 : | <h4>The Metadata Perspective</h4> | ||
| 206 : | This perspective contains three views which allows the user to select a workspace | ||
| 207 : | metadata directory, browse its structure and see supported files contents and | ||
| 208 : | integrity status. | ||
| 209 : | <h4></h4> | ||
| 210 : | <dl> | ||
| 211 : | <dt><b>Workspace Files Spy</b></dt> | ||
| 212 : | <dd>This view allows the user to select a given workspace .metadata directory | ||
| 213 : | and uses a tree view to show a directory hierarchy (having .metadata as root) | ||
| 214 : | containing all known metadata files as leaf nodes. If the user double-clicks | ||
| 215 : | one of these leaf nodes, the Dump Contents view will be opened having this | ||
| 216 : | file as its current selected file. </dd> | ||
| 217 : | <dt><b>Dump Contents</b></dt> | ||
| 218 : | <dd>This view presents to the user the contents of a selected metadata file | ||
| 219 : | in a human-readable format. It provides an action for selecting a new file | ||
| 220 : | to dump. The contents layout will depend on what kind of file is being dumped. | ||
| 221 : | This view has a sub-view called "Dump Summary" that shows whether | ||
| 222 : | the file read was ok or not. </dd> | ||
| 223 : | <dt><b>Dump Summary</b></dt> | ||
| 224 : | <dd>This view presents to the user the results of a file dumped using the Dump | ||
| 225 : | Contents view. In the case of a error during the dumping process (because | ||
| 226 : | the metadata file being dumped was corrupted), the reason will be shown here, | ||
| 227 : | along with the number of bytes read. This view will only be updated if it | ||
| 228 : | is open when a file is being dumped. </dd> | ||
| 229 : | </dl> | ||
| 230 : | <p>Note: the dumping functionality is also available through a command-line tool: | ||
| 231 : | <code>org.eclipse.core.tools.dumper.DumpTool</code>. To run it, you need to | ||
| 232 : | provide the file to be dumped as an argument. Beware the classpath must include | ||
| 233 : | both Spy and Resources plug-ins' JARs. </p> | ||
| 234 : | <h4><a href="hglegal2002.htm"><img SRC="ngibmcpy2002.gif" ALT="Copyright IBM Corporation and others 2000, 2002. All Rights Reserved." BORDER=0 height=14 width=324></a></h4> | ||
| 235 : | </body> | ||
| 236 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |