Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDarin Wright2002-02-06 13:03:27 -0500
committerDarin Wright2002-02-06 13:03:27 -0500
commitcdc66a2abe1f07156b1806c34d91715da0dd11f2 (patch)
tree840461c6607dd551b5f642513c0b49898bd92b73
parent7faa7ac05f5a3176a703066c1db6b6e930901230 (diff)
downloadeclipse.platform.debug-cdc66a2abe1f07156b1806c34d91715da0dd11f2.tar.gz
eclipse.platform.debug-cdc66a2abe1f07156b1806c34d91715da0dd11f2.tar.xz
eclipse.platform.debug-cdc66a2abe1f07156b1806c34d91715da0dd11f2.zip
bug 6485
-rw-r--r--org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html116
-rw-r--r--org.eclipse.debug.core/core/org/eclipse/debug/core/package.html150
2 files changed, 105 insertions, 161 deletions
diff --git a/org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html b/org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html
index acc92a873..951d97dcc 100644
--- a/org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html
+++ b/org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html
@@ -8,50 +8,90 @@
<body bgcolor="#FFFFFF">
-<h3>The Debug Model</h3>
-
-<p><strong>Note:</strong> this package is part of an interim API that is still under
-development and expected to change significantly before reaching stability. It is being
-made available at this early stage to soloicit feedback from pioneering adopters on the
-understanding that any code that uses this API will almost certainly be broken
-(repeatedly) as the API evolves.</p>
-
-<p>A language independent &quot;debug model&quot; is represented by the set of interfaces
-defined in <b>org.eclipse.debug.core.model</b>. A client implements a debug
-model by providing an implementation of these interfaces in a plug-in. (There is no
-explicit extension point that represents a debug model). Each debug architecture will have
-its own way of initiating a debug session. Generally, each debug model will provide one or
-more launchers capable of initiating a debug session. A &quot;launcher&quot; is an
-extension point defined by the debug plug-in. A launcher is responsible for starting a
-debug session, and registering the result with the debug plug-in. Launching is a client
-responsibility.</p>
-
-<p>The common elements defined by the debug plug-in are:
+<p>Defines interfaces for a debug model to support an extensible set of debug architectures.</p>
+
+<h2>Package Specification</h2>
+
+<p>This package defines classes and interfaces known as the &quot;debug model&quot; which support
+an extensible set of debug architectures and languages. The debug model is a set of interfaces
+representing common artifacts in debuggable programs. The debug plug-in itself does not provide
+any implementations of a debug model. It is intended that third parties providing an integrated
+set of development tools for a specific language will also implement a debug model for that language,
+using an underlying debug architecture of their choice. For example, Java Tooling provides an
+implementation of a debug model based on the standard Java Debug Interface (JDI).</p>
+
+<h4>The Debug Model</h4>
+
+<p>A client implements a debug model by
+providing an implementation of the interfaces defined in this package. (There is no explicit
+extension point that represents a debug model). Each debug model provides one or more
+launch configuration types capable of initiating a debug session.</p>
+
+<p>The common elements defined by the debug model are:
<ul>
- <li>Debug Target - a debug target represents a debuggable program - for example, a virtual
+ <li>Debug Target - A debug target represents a debuggable program - for example, a virtual
machine or a process.</li>
- <li>Thread - a debug target may contain one or more threads</li>
- <li>Stack Frame - a thread that is suspended may contain one or more stack frames</li>
- <li>Variable - a stack frame may contain variables</li>
- <li>Value - each variable has a value, and a value may contain more variables (to represent
- complex data structures and objects)</li>
- <li>Process - a program running in normal (non-debug) mode</li>
+ <li>Thread - A debug target may contain one or more threads.</li>
+ <li>Stack Frame - A suspended thread may contain one or more stack frames.</li>
+ <li>Variable - A stack frame may contain variables.</li>
+ <li>Value - Each variable has an associated value, and a value may contain more variables (to
+ represent complex data structures and objects).</li>
+ <li>Register Group - A stack frame may (optionally) be associated with one or more register
+ groups.</li>
+ <li>Register - A register group contains one or more registers.</li>
+ <li>Memory Blocks - A debug target may (optionally) support the retrieval of
+ arbitrary contiguos segments of memory.</li>
+ <li>Breakpoint - Breakpoints suspend the execution of a program.</li>
+ <li>Expression - An expression is a snippet of code that can be evaluated to
+ produce a value.</li>
</ul>
-<h4>Rendering &amp; Presentation</h4>
+<p>A debug model implementation is responsible for firing debug events. A debug event
+corresponds to an event in a program being debugged - for example the creation or
+termination of a thread.</p>
-<p>Debug model elements and breakpoints are displayed in the workbench. To support
-configurable and extensible presentation, the debug UI plug-in defines the <b>
-debugModelPresentations</b> extension point. Extensions of this kind
-register for a specific debug model. It is intended that an implementation of a debug
-model will also provide an implementation of a debug model presentation. The presentation
-provides:
+<h4>Breakpoints</h4>
+
+<p>Breakpoints are used to suspend the execution of a program being debugged. There are
+many kinds of breakpoints - line breakpoints, conditional line breakpoints, hit count
+breakpoints, exception breakpoints, etc. The kinds of breakpoints supported by each debug
+architecture (for example, JDI), and the information required to create those breakpoints
+is dictated by each debug architecture. Eclipse Debug Tools supports an extensible
+set of breakpoint via the breakpoints extension point.</p>
+
+<p>Eclipse Debug Tools provides a breakpoint manager that maintains the collection of all
+registered breakpoints. Clients add and remove breakpoints via this manager. Breakpoints are
+implemented by instances of IBreakpoint. Each breakpoint object has an associated marker,
+which provides persistence and presentation in editors. Eclipse Debug Tools defines a generic
+breakpoint and line breakpoint, as well as their corresponding marker definitions. Breakpoint
+creation is a client responsibility - that is, defining the attributes of a breakpoint and
+the resource to associate a breakpoin marker with.</p>
+
+<p>Breakpoint creation is a client responsibility, as the location in which a breakpoint may
+be placed, and the attributes that a debug target requires to install a breakpoint is
+specific to each debug architecture.</p>
+
+<h5>Persistence</h5>
+
+<p>Breakpoints are persisted via their underlying marker. Breakpoint markers defined
+with the <b>persisted</b> attribute as <b>false</b> will not be persisted. Breakpoints
+are restored at workspace startup time by the breakpoint manager - that is, breakpoint objects
+are created for all persisted markers which are a subtype of the root breakpoint marker
+and are added to the breakpoint manager. To allow for selective persistence
+of breakpoints (of the same kind), the IBreakpoint interface and root breakpoint
+implementation define a &quot;persisted&quot; attribute. If this value is set to false,
+the breakpoint will not be persisted across workspace invocations.</p>
+
+<h5>Change Notification</h5>
+
+<p>As breakpoint markers are modified (created, removed, and changed), resource deltas
+are created by the platform. The breakpoint manager translates pertinent resource deltas
+into breakpoint change notifications (breakpoint added/removed/changed messages). Interested
+listeners may register with the breakpoint manager. The breakpoint manager only fires change
+notifications for registered breakpoints. This simplifies breakpoint processing for clients,
+as resource delta traversal and analysis is not required. Debug targets that support breakpoints
+should register for breakpoint change notifications.</p>
-<ul>
- <li>an image for a debug element or breakpoint</li>
- <li>a label for a debug element or breakpoint</li>
- <li>an editor input that should be used to display a debug element or breakpoint</li>
-</ul>
</body>
</html>
diff --git a/org.eclipse.debug.core/core/org/eclipse/debug/core/package.html b/org.eclipse.debug.core/core/org/eclipse/debug/core/package.html
index 642cb7f93..45d261dbf 100644
--- a/org.eclipse.debug.core/core/org/eclipse/debug/core/package.html
+++ b/org.eclipse.debug.core/core/org/eclipse/debug/core/package.html
@@ -8,152 +8,56 @@
<body bgcolor="#FFFFFF">
-<p>Provides support for launching programs and defines interfaces for a debug model to
-support an extensible set of debug architectures.</p>
+<p>Provides support for launching programs, breakpoint management, expression management,
+and debug events.</p>
<h2>Package Specification</h2>
-<p>Eclipse Debug Tools provides classes and interfaces to support the launching,
-registration, and manipulation of debuggable and non-debuggable programs. An extensible
+<p>This package provides classes and interfaces to support facilities common
+among many debug architectures: launching programs, breakpoint management,
+expression management, and debug events. An extensible
set of debug architectures and languages are supported by the definition of a &quot;debug
-model&quot; - a set of interfaces representing common artifacts in debuggable programs.
+model&quot; - a set of interfaces representing common artifacts in debuggable programs, which
+are defined in <b>org.eclipse.debug.core.model</b>.
The debug plug-in itself does not provide any implementations of a debug model. It is
intended that third parties providing an integrated set of development tools for a
specific language will also implement a debug model for that language, using an underlying
debug architecture of their choice. For example, Java Tooling provides an implementation
of a debug model based on the standard Java Debug Interface (JDI).</p>
-<h4>The Debug Model</h4>
+<h4>The Managers</h4>
-<p>The &quot;debug model&quot; is represented by the set of interfaces defined in <b>
-org.eclipse.debug.core.model</b>. A client implements a debug model by
-providing an implementation of these interfaces in a plug-in. (There is no explicit
-extension point that represents a debug model). Each debug architecture will have its own
-way of initiating a debug session. Generally, each debug model will provide one or more
-launch configuration types capable of initiating a debug session. A &quot;launch configuration type&quot;
-is an extension point defined by the debug plug-in. A launch configuration (instance of a
-launch configuration type) is responsible for starting a debug session. Launching is a client
-responsibility.</p>
-
-<p>The common elements defined by the debug plug-in are:
-
-<ul>
- <li>Debug Target - A debug target represents a debuggable program - for example, a virtual
- machine or a process.</li>
- <li>Thread - A debug target may contain one or more threads.</li>
- <li>Stack Frame - A suspended thread may contain one or more stack frames.</li>
- <li>Variable - A stack frame may contain variables.</li>
- <li>Value - Each variable has an associated value, and a value may contain more variables (to
- represent complex data structures and objects).</li>
- <li>Register Group - A stack frame may (optionally) be associated with one or more register
- groups.</li>
- <li>Register - A register group contains one or more registers.</li>
- <li>Memory Blocks - A debug target may (optionally) support the retrieval of
- arbitrary contiguos segments of memory.</li>
- <li>Breakpoint - Breakpoints suspend the execution of a program, and are
- debug architecture specific.</li>
- <li>Expression - An expression is a snippet of code that can be evaluated to
- produce a value. When and how an expression is evaluated is implementation
- specific.</li>
-</ul>
-
-<p>A debug model implementation is responsible for firing debug events. A debug event
-corresponds to an event in a program being debugged - for example the creation or
-termination of a thread.</p>
-
-<h5>Rendering &amp; Presentation</h5>
-
-<p>Debug model elements and breakpoints are displayed in the workbench. To support
-configurable and extensible presentation, the<b> debugModelPresentations</b>
-extension point is used. Extensions may be registered for a specific debug model. It is
-intended that an implementation of a debug model will also provide an implementation of a
-debug model presentation. The presentation provides:
-
-<ul>
- <li>an image for a debug element or breakpoint</li>
- <li>a label for a debug element or breakpoint</li>
- <li>an editor input that should be used to display a debug element or breakpoint</li>
-</ul>
-
-<h4>The Debug Managers</h4>
-
-<p>Eclipse Debug Tools defines and provides an implementation the following managers:
+<p>Eclipse Debug Tools defines and provides an implementation of the following managers:
<ul>
- <li>Launch Manager - The launch manager maintains the set of registered launches. That is,
- a collection of programs that have been launched in debuggable or non-debuggable mode.
+ <li>Launch Manager - The launch manager maintains the set of registered launches - that is,
+ a collection of programs that have been launched in debuggable or non-debuggable (run) mode.
Each launch maintains its associated debug targets and system processes. A launch that
represents a debuggable program may specify an associated source locator used to locate
source elements associated with stack frames for a particular debug session. Clients must
provide implementations of source locators, which are generally tied to the manner in which
- a program is launched.
- <li>Breakpoint Manager - The breakpoint manager maintains, persists, and restores, and
- provides change notification of breakpoints. See below for more information on breakpoints.
+ a program is launched.</li>
+ <li>Breakpoint Manager - The breakpoint manager maintains, persists, and restores the collection
+ of all registered breakpoints in the workspace. As well, it provides change notification for
+ breakpoints.</li>
<li>Expression Manager - The expression manager maintains a collection of registered expressions.
Expressions are not automatically persisted, but a client could persist its own expressions
- if required.
+ if required.</li>
</ul>
</p>
-<h4>Breakpoints</h4>
-
-<p>Breakpoints are used to suspend the execution of a program being debugged. There are
-many kinds of breakpoints - line breakpoints, conditional line breakpoints, hit count
-breakpoints, exception breakpoints, etc. The kinds of breakpoints supported by each debug
-architecture (for example, JDI), and the information required to create those breakpoints
-is dictated by each debug architecture. Eclipse Debug Tools supports an extensible
-set of breakpoint types.</p>
-
-<p>Eclipse Debug Tools provides a breakpoint manager that maintains the collection of all
-registered breakpoints. Clients add and remove breakpoints via this manager. Breakpoints are
-implemented by instances of IBreakpoint. Each breakpoint object has an associated marker,
-which provides persistence and presentation in editors. Eclipse Debug Tools defines a generic
-breakpoint and line breakpoint, as well as their corresponding marker definitions. Breakpoint
-creation is a client responsibility - that is, defining the attributes of a breakpoint and
-the resource to associate a breakpoin marker with.</p>
-
-<h5>Breakpoint Creation</h5>
-
-<p>Since the location in which a breakpoint may be placed, and the attributes that its
-debug target requires to install the breakpoint is specific to each launguage/debug model,
-breakpoint creation is a client responsibility. Generally, breakpoint creation involves
-the following steps:
-
-<ol>
- <li>Creation of a breakpoint object and associated marker.</li>
- <li>Registration of the breakpoint with the breakpoint manager. A breakpoint is not
- considered active until it is registered with the breakpoint manager.</li>
-</ol>
-
-<h5>Persistence</h5>
-
-<p>Breakpoints are persisted via their underlying marker. Breakpoint markers defined
-with the <b>persisted</b> attribute as <b>false</b> will not be persisted. Breakpoints
-are restored at workspace startup time by the breakpoint manager - that is, breakpoint objects
-are created for all persisted markers which are a subtype of the root breakpoint marker
-and are added to the breakpoint manager. To allow for selective persistence
-of breakpoints (of the same kind), the IBreakpoint interface and root breakpoint
-implementation define a &quot;persisted&quot; attribute. If this value is set to false,
-the breakpoint will not be persisted.</p>
-
-<h5>Change Notification</h5>
-
-<p>As breakpoint markers are modified (created, removed, and changed), resource deltas
-are created by the platform. The breakpoint manager translates pertinent resource deltas
-into breakpoint change notifications (breakpoint added/removed/changed messages). Interested
-listeners may register with the breakpoint manager. The breakpoint manager only fires change
-notifications for registered breakpoints. This simplifies breakpoint processing for clients,
-as resource delta traversal and analysis is not required. Debug targets that support breakpoints
-should register for breakpoint change notifications.</p>
-
+<h4>Launch Configurations</h4>
-<h5>Extensibility</h5>
+<p>A launch configuration is a persistable description of how to launch an application.
+ Each launch configuration is an instance of a type of launch configuration - for example,
+ a Java Application. The debug plug-in defines a launch configuration type extension point
+ such that clients may define launch configurations specific to their debug architecture.
+ A launch configuration is simply a set of attributes describing how to launch a program.
+ The actual launching of an application is performed
+ by an associated implementation of a launch configuration delegate, which is specifed by each launch configuration
+ type extension.</p>
+<p>A launch configuration may be shared in a repository via standard VCM mechanisms, or may
+ be stored locally, essentially making the launch configuration private for a single user.</p>
-<p>Clients can define new kinds of breakpoints with the appropriate plug-in XML and
-subtyping any of the defined breakpoint objects and markers. For example, a client
-may define an exception breakpoint as a subtype of the root breakpoint, or a client
-might define a conditional breakpoint as a subtype of the line breakpoint. The breakpoint
-manager does not define generic breakpoints of these types since the attributes required
-are debug model dependent.</p>
</body>
</html>

Back to the top