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 "Debug/Plan/3.6/Launch Templates"

(Rename a template)
(Design Decisions)
 
(45 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
The following use cases are intended to be used a starting point for launch configuration template design and integration into the debug platform.
 
The following use cases are intended to be used a starting point for launch configuration template design and integration into the debug platform.
  
=== Create a new template ===
+
Templates behave like cookie cutters. A configuration can be based on a template, which seeds attributes in the configuration with the settings specified in the template. Once a configuration has been created, the user can override any initial settings from the template. The user can also modify the template and push changes out to the configurations based on it. A configuration maintains a backpointer to its template, but is a complete standalone congifuration than can be launched, exported, shared, etc.
  
To creating a template use the "New" drop down button in the LCD tree viewer toolbar, and select "Template".
+
=== Design Decisions ===
  
=== Create a template from an existing configuration ===
+
Launch configurations are relatively simple attribute/value data structures. However, a launch configuration can use the absence of an attribute to indicate important data. For example, when the JRE attribute is not present for Java Application launch configurations, it indicates that the project (or workspace) default JRE should be used (depending on whether the configuration is associated with a project). This imposes a limitation on template implementation: simply copying attributes from a template to a configuration does not work for template application - as this does not cause unspecified attributes to be removed.
  
Select the configuration in the LCD and click the "Template" toolbar button.
+
For example, when a configuration specifies a specific JRE and a template specifies a default JRE (null), copying attributes will result in the specific JRE setting to remain in the configuration. For this reason it is important to persist "null" and "removed" values in configuration templates. This adds to the complexity of templates - as templates will often be incomplete. For example, a template would not often contain a main type name to launch - that whould usually be specified by individual configurations. So, if the template contained a null or empty main type name, we would not want this to cause the main type name in configurations to be wiped out.
  
A configuration will automatically become a template if an existing configuration is dropped on it as a child configuration.
+
For these reasons, it is important that templates contain only the relevant (sub)set of attributes that they define, and that null/removed values are also persisted in the template. This also imposes restrictions in the user interface implementation. If all launch tabs are present for a template, all attributes will be present in that template - and effectively override all settings its children configurations. To solve this problem, a subset of tabs could be allowed for templates - and the user should decide which tabs are going to be present in their template. It also means that the effectiveness of templates depends on the existing set of attributes grouped on each tab, as each tab will be applied in its entirety to its children configurations. (The platform has no way of associating attributes with launch tab controls, so this is the finest granularity it can offer with existing APIs).
  
=== Assign a default template to a project ===
+
{{bug2|41353|Launch Templates}}
  
A default template can be set for each launch configration type, for each project. From the "Properties > Run/Debug Settings" for a project, the user can use check boxes to select the default configuration for a project (the viewer in the properties page will become a check box list). Similarly, we could allow a default template to be set for any workspace folder, to allow for a rich set of default configurations.
+
=== Create a new template ===
  
An API will be available to set a default template per launch configuration type for any given scope (using IScopeContext's - the same construct used for workspace preference settings). This allows a default template per launch configuration type to be set using a project scope.
+
To creating a template use the "New" drop down button in the LCD tree viewer toolbar, and select "Template".
 +
 
 +
=== Create a template from an existing configuration ===
  
=== Assign a default template to a workspace ===
+
Select the configuration you would like to make into a template, and then select "New > Template" from the context menu or drop down tool bar action.
 +
A template is created with the contents of the selected configuration. And the existing configuration becomes a child of the template.
  
A default template can be set for each launch configuration type in the workspace. When a launch configuration type is selected in the LCD, the tab area will be enhanced to display a check box list of all templates of that type. The check box can be used to select one template as workspace default for that type.
+
When a configuration, based on a template, is selected and the use chooses to make it a template, a new template will appear at the root (2nd level of the tree), based on the configuration. The action creates a new template based on the selected configuration.
  
 
=== Create a configuration based on a specific template ===
 
=== Create a configuration based on a specific template ===
Line 28: Line 31:
  
 
Alternatively, double-clicking on an existing template will create a configuration based on that template.
 
Alternatively, double-clicking on an existing template will create a configuration based on that template.
 
=== Create a configuration based on a project/workspace default template ===
 
 
When a new template is created in the LCD or from invoking a launch shortcut, project and workspace default template settings should be taken into account to initialize newly created configurations. The debug platform can leverage configuration resource mappings to determine what template should be used to initialize newly created configurations.
 
 
* Select a launch configuration type node in the LCD and press the "New" button. This will create a new configuration and initialize it with default settings - ususally based on the selected resource or active editor in the workbench and usually sets a resource mapping for the configuration. The platform will locate a template based on project and workspace default settings for the configuration type and copy attributes from the first template found into the new configuration.
 
 
* Similarly, when a launch shortcut creates a configuration and sets a resource mapping, this will trigger template initialization.
 
 
Additionally, and API will be available to create a configuration based on a set of scopes (the same as preference scopes - project, workspace, etc.), and set a default configuration for a given scope. A launch shortcut could use the new API to explicitly control what template is used (if any) when creating a new configuration. However, to allow existing shortcuts to benefit from launch templates, resource mappings will be used to trigger template initialization.
 
  
 
=== Update all configurations made from a template ===
 
=== Update all configurations made from a template ===
  
From time to time, attributes in a template will be modified. When the "Apply" button is pressed the user will be prompted to update all children configurations (and have the option to "do not ask again").
+
From time to time, attributes in a template will be modified. When the "Propogate..." button is pressed (in place of run/debug buttons) the user will be prompted to update all children configurations (and have the option to "do not ask again"). The dialog will allow for selective update (check box selection) to children configurations.
 
+
A button should also be available in the toolbar to apply a template to all of its children.
+
  
 
=== Rename a template ===
 
=== Rename a template ===
Line 51: Line 42:
 
=== Delete a template ===
 
=== Delete a template ===
  
When a template is deleted in the LCD, users could be prompted to update all configurations assocaited with the template (i.e. to no longer be assocaited with the template). The user could decide not to update associated configurations such that the template could later be replaced and all references would become satisfied.
+
When a template is deleted in the LCD, users will be prompted to delete all children assocaited with the template. When children are not deleted, they are moved up a level in the tree (re-parented).
  
=== Remove template status ===
+
=== Disconnect a configuration from its template ===
  
A template can be made into an ordinary configuration by unchecking the "Template" box in the LCD. The user could be prompted to update all referencing configurations (similar to when a template is deleted).
+
Drag & drop allows a user to re-parent a configuration to a different template or to no template (dropping on configuration type node).
 
+
=== Disconnect a configuration from its template ===
+
  
The template controls in the LCD show that a configuration is "Based on template: [X]". The user can disassociate a configuration with a its template by unchecking this check box.
+
Could have "Move..." action with a list of templates or root node (no template).
  
 
=== Associate a configuration with an existing template ===
 
=== Associate a configuration with an existing template ===
  
A template can be associated with an existing template, or associated with a different template by using the "Templates..." button next to the "Based on template: [X]" controls. This will present the user with a list of potential templates. The configruation will then be assocaited with the selected template. The user can use the "Restore" button to synchronize settings. The selection dialog could have an option to restore when OK is pressed.
+
A configuration can be associated with an existing template using drag & drop (dropping on the template). When this happens, the user will be prompted to apply the template settings to the freshly dropped configuration (with a "do not ask again" option).
  
 
== Launch Configuration Template User Interface ==
 
== Launch Configuration Template User Interface ==
  
=== Checkbox viewer on launch configuration type page ===
+
=== Display template relationships and provide convenience actions ===
  
Currently, when a launch configuration type is selected in the LCD, a page of instructions is displayed on how to create and manage launch configrations. We can add a check box list to this page showing all templates of the selected type. The checked template specifies the workspace default template.
+
The launch configuration editing area will be enhanced as follows:
  
=== Checkbox viewer on Run/Debug settings property page ===
+
* The "Name:" label will be changed to "Template Name:" when editing/displaying a template.
  
Currently, the Run/Debug settings property page is a flat list. We will make this into a check box list for projects such a that a default template can be specified at the project level.
+
The LCD tree viewer will be enhanced with the following:
  
=== LCD tree viewer ===
+
* The "New" button will be enhanced into a drop down to allow a new "Configuration" or "Template" to be created. By default (i.e. just pressing the button), a confiugration will be created.
 
+
* Nest configurations by template - i.e. all configurations based on a template will be displayed as children of that template.
* The "New" button will be enhanced to be a drop down to allow a new "Configuration" or "Template" to be created.
+
* Double-clicking a template in the tree will create a new configration based on that template
* The tree viewer in the LCD will nest configurations by templates - i.e. all children of a template will be displayed as children of that template in the tree.
+
* Drag & drop to allow configurations to be re-parented under a different template (or disasscoiated with its template by dragging to the top level).
* Double-clicking a template in the tree will create a new configration based on the clicked template
+
* The tree will support drag & drop to allow configurations to be re-parented under a different template (or disasscoiated with any template by dragging to the top level).
+
* A button will be added to the toolbar to allow the selected template to be applied/pushed to all children.
+
  
 
== Launch Configuration Template API ==
 
== Launch Configuration Template API ==
Line 89: Line 75:
 
=== ILaunchConfigurationType ===
 
=== ILaunchConfigurationType ===
  
* Set a default template for a specified scope (or remove when null)
 
* Get the default template for a given scope (may return null)
 
 
* Get all templates of this type
 
* Get all templates of this type
* Create a new working copy based on a given set of scopes
+
* Create a new working copy based on a given template
  
 
=== ILaunchConfigurationWorkingCopy ===
 
=== ILaunchConfigurationWorkingCopy ===
  
 
* Set whether a configuration is a template
 
* Set whether a configuration is a template
* Set the template a configuration is based on
+
* Set the template a configuration is based on (backpointer)
* Copy attributes from a template (any configuration) into the working copy
+
* Copy attributes from a configuration into the working copy
  
 
=== ILaunchConfiguration ===
 
=== ILaunchConfiguration ===
  
 
* Return whether a configuration is a template
 
* Return whether a configuration is a template
* Get the template a configuration is based on (may be null)
+
* Get the template a configuration is based on (backpointer, may be null)
 
* Get all configurations a template is associated with
 
* Get all configurations a template is associated with
 +
 +
=== AbstractLaunchConfigurationTab ===
 +
 +
* A new method to validate templates. The default implementation will not validate templates (as they will usually have sparse/incomplete information that would be invalid). Clients can provide an implementation of the new method to perform template validation as needed.
 +
 +
=== Images ===
 +
 +
* The launchConfigurationTypeImages extension will be enhanced to allow a custom image to be provided for templates. When no image is provided the platform could use a default template image (or we could experiment with disabled images).
 +
 +
== Default Launch Configuration Settings (Workspace, Project preferences) ==
 +
 +
Related to launch configuration templates, are default workspace and project settings for launch configurations. Users can acheive features similar to default workspace/project settings by managing templates, but the SDK could also offer explicit support for this.
 +
 +
A user may want to define default settings for certain launch aspects. For example, a default JRE or VM arguments to use for all Java applications. Although this could be achieved with a template, one could imagine having default settings that could be applied to newly created launch configurations. Default settings work like preferences - they are used to override settings in specific launch configurations, but the launch configurations themselves contain no backpointer/reference to the settings (unlike a configuration based on a template, which keeps track of which template it was based on). The user can maintain a hierarchy of templates orthoganal to default settings. Newly created templates would obtain default settings the same way a configuration would.
 +
 +
=== Define default launch settings for a workspace ===
 +
 +
Default workspace settings can be defined for each launch configuration type available in the workspace. A toggle button would be present in the LCD to set a configuration as default for the workspace. The label of the workspace default configration will be bolded and have a "(workspace default)" qualifier.
 +
 +
=== Initializing a configuration based on workspace default settings ===
 +
 +
Workspace default settings should initialize newly created configurations when created in the LCD or by invoking a launch shortcut.
 +
 +
=== Issues with project/resource based default settings ===
 +
 +
It might be useful to have project or resource based default settings. Hoewver, this is problematic as the API used to create a configuration does not currently specify a resource context (and thus the platform cannot infer which template to base a configuration  on).
 +
 +
One could imagine using resource mappings, but this delays the template assocaition until the time when a new working copy is saved (i.e. for the first time only), its resource mapping will be used to determine what settings (i.e. which scope - project or workspace) should be used to initialize the working copy. Any default settings found, will be applied to the working copy. The platform cannot determine the proper scope to use until the configuration is saved, as when a configuration is created, a resource scope is not provided. As well, the scope may change while the working copy is being edited.
 +
 +
[[Debug/Plan/3.6|Debug 3.6 Plan]]

Latest revision as of 15:30, 12 November 2009

Launch Configuration Template Use Cases

The following use cases are intended to be used a starting point for launch configuration template design and integration into the debug platform.

Templates behave like cookie cutters. A configuration can be based on a template, which seeds attributes in the configuration with the settings specified in the template. Once a configuration has been created, the user can override any initial settings from the template. The user can also modify the template and push changes out to the configurations based on it. A configuration maintains a backpointer to its template, but is a complete standalone congifuration than can be launched, exported, shared, etc.

Design Decisions

Launch configurations are relatively simple attribute/value data structures. However, a launch configuration can use the absence of an attribute to indicate important data. For example, when the JRE attribute is not present for Java Application launch configurations, it indicates that the project (or workspace) default JRE should be used (depending on whether the configuration is associated with a project). This imposes a limitation on template implementation: simply copying attributes from a template to a configuration does not work for template application - as this does not cause unspecified attributes to be removed.

For example, when a configuration specifies a specific JRE and a template specifies a default JRE (null), copying attributes will result in the specific JRE setting to remain in the configuration. For this reason it is important to persist "null" and "removed" values in configuration templates. This adds to the complexity of templates - as templates will often be incomplete. For example, a template would not often contain a main type name to launch - that whould usually be specified by individual configurations. So, if the template contained a null or empty main type name, we would not want this to cause the main type name in configurations to be wiped out.

For these reasons, it is important that templates contain only the relevant (sub)set of attributes that they define, and that null/removed values are also persisted in the template. This also imposes restrictions in the user interface implementation. If all launch tabs are present for a template, all attributes will be present in that template - and effectively override all settings its children configurations. To solve this problem, a subset of tabs could be allowed for templates - and the user should decide which tabs are going to be present in their template. It also means that the effectiveness of templates depends on the existing set of attributes grouped on each tab, as each tab will be applied in its entirety to its children configurations. (The platform has no way of associating attributes with launch tab controls, so this is the finest granularity it can offer with existing APIs).

Bug.png
41353
Launch Templates


Create a new template

To creating a template use the "New" drop down button in the LCD tree viewer toolbar, and select "Template".

Create a template from an existing configuration

Select the configuration you would like to make into a template, and then select "New > Template" from the context menu or drop down tool bar action. A template is created with the contents of the selected configuration. And the existing configuration becomes a child of the template.

When a configuration, based on a template, is selected and the use chooses to make it a template, a new template will appear at the root (2nd level of the tree), based on the configuration. The action creates a new template based on the selected configuration.

Create a configuration based on a specific template

Select the template in the LCD and press the "New" button. This will create a new configuration associated with the selected template, initialized with attributes from the template.

Alternatively, double-clicking on an existing template will create a configuration based on that template.

Update all configurations made from a template

From time to time, attributes in a template will be modified. When the "Propogate..." button is pressed (in place of run/debug buttons) the user will be prompted to update all children configurations (and have the option to "do not ask again"). The dialog will allow for selective update (check box selection) to children configurations.

Rename a template

Launch configurations keep track of which template (if any) they are based on. When a template is renamed in the LCD, all configurations made from that template will be updated to refer to the renamed template. This is much like a refactoring.

Delete a template

When a template is deleted in the LCD, users will be prompted to delete all children assocaited with the template. When children are not deleted, they are moved up a level in the tree (re-parented).

Disconnect a configuration from its template

Drag & drop allows a user to re-parent a configuration to a different template or to no template (dropping on configuration type node).

Could have "Move..." action with a list of templates or root node (no template).

Associate a configuration with an existing template

A configuration can be associated with an existing template using drag & drop (dropping on the template). When this happens, the user will be prompted to apply the template settings to the freshly dropped configuration (with a "do not ask again" option).

Launch Configuration Template User Interface

Display template relationships and provide convenience actions

The launch configuration editing area will be enhanced as follows:

  • The "Name:" label will be changed to "Template Name:" when editing/displaying a template.

The LCD tree viewer will be enhanced with the following:

  • The "New" button will be enhanced into a drop down to allow a new "Configuration" or "Template" to be created. By default (i.e. just pressing the button), a confiugration will be created.
  • Nest configurations by template - i.e. all configurations based on a template will be displayed as children of that template.
  • Double-clicking a template in the tree will create a new configration based on that template
  • Drag & drop to allow configurations to be re-parented under a different template (or disasscoiated with its template by dragging to the top level).

Launch Configuration Template API

API will added to the following interfaces to support launch configuration templates

ILaunchConfigurationType

  • Get all templates of this type
  • Create a new working copy based on a given template

ILaunchConfigurationWorkingCopy

  • Set whether a configuration is a template
  • Set the template a configuration is based on (backpointer)
  • Copy attributes from a configuration into the working copy

ILaunchConfiguration

  • Return whether a configuration is a template
  • Get the template a configuration is based on (backpointer, may be null)
  • Get all configurations a template is associated with

AbstractLaunchConfigurationTab

  • A new method to validate templates. The default implementation will not validate templates (as they will usually have sparse/incomplete information that would be invalid). Clients can provide an implementation of the new method to perform template validation as needed.

Images

  • The launchConfigurationTypeImages extension will be enhanced to allow a custom image to be provided for templates. When no image is provided the platform could use a default template image (or we could experiment with disabled images).

Default Launch Configuration Settings (Workspace, Project preferences)

Related to launch configuration templates, are default workspace and project settings for launch configurations. Users can acheive features similar to default workspace/project settings by managing templates, but the SDK could also offer explicit support for this.

A user may want to define default settings for certain launch aspects. For example, a default JRE or VM arguments to use for all Java applications. Although this could be achieved with a template, one could imagine having default settings that could be applied to newly created launch configurations. Default settings work like preferences - they are used to override settings in specific launch configurations, but the launch configurations themselves contain no backpointer/reference to the settings (unlike a configuration based on a template, which keeps track of which template it was based on). The user can maintain a hierarchy of templates orthoganal to default settings. Newly created templates would obtain default settings the same way a configuration would.

Define default launch settings for a workspace

Default workspace settings can be defined for each launch configuration type available in the workspace. A toggle button would be present in the LCD to set a configuration as default for the workspace. The label of the workspace default configration will be bolded and have a "(workspace default)" qualifier.

Initializing a configuration based on workspace default settings

Workspace default settings should initialize newly created configurations when created in the LCD or by invoking a launch shortcut.

Issues with project/resource based default settings

It might be useful to have project or resource based default settings. Hoewver, this is problematic as the API used to create a configuration does not currently specify a resource context (and thus the platform cannot infer which template to base a configuration on).

One could imagine using resource mappings, but this delays the template assocaition until the time when a new working copy is saved (i.e. for the first time only), its resource mapping will be used to determine what settings (i.e. which scope - project or workspace) should be used to initialize the working copy. Any default settings found, will be applied to the working copy. The platform cannot determine the proper scope to use until the configuration is saved, as when a configuration is created, a resource scope is not provided. As well, the scope may change while the working copy is being edited.

Debug 3.6 Plan

Back to the top