Launching

["Darin Wright/WPG/OTI" <Darin_Wright@xxxxxxx>]

The debug team is planning to implement "launch configurations". A launch
configurations is a persisted description of how to launch a program.
Launch configurations are intended to address the usability issues of
running a program with different combinations command line arguments, JREs,
etc. Attached is an informal design doc of use cases describing how the
debug team plans to tackle the problem.

Any feedback is appreciated.

(See attached file: LaunchConfigurations.htm)

Darin

Title: Launch Configurations

Launching

Motivation for change

Currently, launching a Java program requires the user to configure settings in different locations. For example, the JRE can be specified via the workbench preferences or a project's properties. Command line arguments and VM arguments are set via the properties of the compilation unit (and it is only possible to persist one set of arguments, which are not shared with the team). The launch wizard does not currently allow the configuration of JRE or arguments when launching a Java program. It would be more desirable to have a centralized launch configuration where all parameters of a launch could be specified, and allow for multiple configurations per program.

The launch wizard does not currently quickly enable the user to complete a launch. That is, the user is forced to choose a launcher, and then press "next" even though there may only be once choice on the next page. This is done because a launcher may be required to perform a "long operation" to determine if the next page can finish. Rather than have the wizard "hang", we do not enable "finish" from the first/second launch wizard pages.

Currently, a default launcher is not set for a project when it is created, and the first time a user launches a project they must specify which launcher to use.

Proposal

We would like to make simple launching simpler (i.e. the first time user should just have to point and click). We would like to make advanced launching easier to configure, share, and re-use. To support advanced launching, we introduce the notion of a "launch configuration", which is a persisted description of how to launch a program.

Requirements

• Easy first launch
• Centralized configuration for advanced launching
• Persisted launch history
• Share launch configurations in repository
• Allow for “local-only” launch configurations
• Programmatic launch capability
• Easy re-launch (most recent)
• Extensible launch options
• Launch programs that do not exist as resources in the workspace (i.e. launching a main from an external jar)

Terms

• Launch – the result of launching
• Launch Configuration – an object that stores a collection of attributes on how to launch an application, which is capable of launching that application
• Mode – a mode that an application can be launched in. There are two mutually exclusive modes - RUN and DEBUG. If a program is not under control of a debugger, it is considered to be in RUN mode. For example, a program may be running with a trace option, but not under control of a debugger. This is considered RUN mode with a "trace" option.
• Options – an extensible set of client defined set of options, such as “trace”, “analyze”, “verbose”, etc.

Use Cases

Following are a set of use cases that describe how launching/launch configurations would appear to the end user.

Point and Click (Click)

• (Assume no launches have been performed in the workspace)
• Select a compilation unit with a main method in a navigator (or have the compilation unit open in the active editor)
• Press "Run" or "Debug"
• The “Launch Configuration” dialog is opened. The dialog presents a tree on the left hand side, and a tabbed pane on the right and side. The tree displays existing launch configurations (none currently), grouped by configuration types, which are top-level nodes in the tree (Java Application, Remote Java Application, etc). Leaf nodes are instances of configurations. There are three buttons above the configuration tree – New, Delete, and Copy. There is a check box below the tree labeled “Default configuration type for project XXX” (which is checked). Above the right hand tabbed pane area is a text field where the name of the currently selected configuration is displayed. Below the tabbed pane area are three buttons “Save”, “Save & Launch”, and “Launch”. There is also a cancel button on the dialog. At the top of the dialog, the current project is displayed in a text field. The list of configurations is populated based on the selected project. A different project can be selected by typing in a new name, or by using a “browse” button to select from a list of projects. Below the project selection, the mode in which the program will be launched is displayed (run or debug), and the user can change the mode at this point via radio buttons.
• By default, the kind of application to run/debug is already selected – Java Application. (If a project has a default configuration associated with it, a new configuration of that kind is created when Run/Debug is pressed).
• The tabbed pane of the dialog is populated with the tabbed pages to configure a Java Application, and is filled with default values. The tabbed panes are (something like) “Main”, “JRE”, “Command Line”, “Team”, and “Perspective”. The first three panes are contributed by the Java Application launch configuration, and the last two (Team & Perspective) are contributed by the debug UI plug-in, as they contain settings pertinent to all launch configurations.
• The name is filled in with a default value – the name of the main type associated with the selected compilation unit in the workbench.
• The “Main” tab allows a main class and program arguments to be specified (for a simple launch, these are the only parameters that need be specified).
• The “main” class to run is filled in with a default value – the name of the main type associated with the selected compilation unit in the workbench. There is a browse button beside this field, which allows the user to search for a main type to run (from all types in the project with a main method).
• By default, the program arguments are blank.
• [The “JRE” tab allows specification of a runtime JRE, and by default is that of the workspace JRE. From this page, new JRE’s can also be defined.]
• [The “Command Line” tab shows the command line that will be used to run the program, and allows the user to use the default, or specify a custom command line manually by clicking a checkbox to “modify command line”, and then letting the user edit the command line in a text editor.  This is where the user could edit the bootpath.]
• [The “Team” tab specifies if the configuration should be shared with the team, or made local. By default the configuration is local. When shared, the configuration is added to the project’s “.launches” directory stored in the project folder. The folder contains “.launch” files - one per launch configuration. Local configurations are stored in the metadata area.]
• [The “Perspective” tab allows the user to specify which perspective (if any) should be shown when the configuration is launched. By default, the debug perspective is displayed when a configuration is launched. However, this can be overridden to specify a perspective for all modes, or a perspective per mode.]
• Press “Launch” - the program is launched in run or debug mode (depending which button was pressed).

Notes

The point and click scenario in this case requires input from the user. The user must click twice – once to realize the launch dialog and once to launch. A user does not need to save a configuration (and in the scenario above, they did not). Since “save” was not pressed the configuration will not be saved – it will only exist in the launch history.

 

Be default there is no “default launch configuration type” associated with a project. However, a project creation wizard (like the Java Project creation wizard), should specify a default launch configuration type for a project, which streamlines launching for the user.

Creating a new launch configuration

• Select a compilation unit with a main method in a navigator (or have the compilation unit open in the active editor)
• Press "Run" or "Debug"
• The “Launch Configuration” dialog is opened.
• By default, the kind of application to run is already selected – Java Application. (If a project has a default configuration associated with it, a new configuration of that kind is created when Run/Debug is pressed).
• The tabbed pane of the dialog is populated with the tabbed pages to configure a Java Application, and is filled with default values.
• The “Main” tab allows a main class and program arguments to be specified.
• The “main” class to run is filled in with a default value – the name of the main type associated with the selected compilation unit in the workbench.
• By default, the program arguments are blank, but may be specified.
• The “JRE” tab allows specification of a runtime JRE, and by default is that of the workspace JRE. From this page, new JRE’s can also be defined.
• The “Command Line” tab shows the command line that will be used to run the program, and allows the user to use the default, or specify a custom command line manually by clicking a checkbox to “modify command line”, and then letting the user edit the command line in a text editor.
• The “Team” tab specifies if the configuration should be shared with the team, or made local. By default the configuration is local. When shared, the configuration is added to the project’s “.launches” folder located in the project folder. The folder contains one “.launch” file per launch configuration. Local configurations are stored in the metadata area.
• The “Perspective” tab allows the user to specify which perspective (if any) should be shown when the configuration is launched. By default, the debug perspective is to be displayed when launched in any mode. However, this can be overridden to specify a perspective for all modes, or a perspective per mode.
• Press “Save”, and the configuration is added to the configuration list in the left hand tree, under “Java Applications”. The save button becomes disabled, as there are no longer any changes to save.

Re-launching (History)

• Pressing F-10 re-launches the most recently launched configuration, in the mode it was last launched.
• The drop-down menus can be used to re-launch a configuration in the launch history. When a configuration is launched, it is placed in the debug history menu if it supports DEBUG mode, and it is placed in the run history menu if it supports the RUN mode.

Notes

When a launch configuration is launched, it returns the resulting launch object. The launch object contains a method to retrieve the configuration that was launched. Launch configuration objects are placed in the launch history, and are persisted across workbench invocations.

Selecting a configuration to launch

• From the Run or Debug drop down menu, select "Run..." or “Debug…”
• The Launch configuration dialog appears showing all configurations in the current project.
• Choose the desired configuration and press "Launch"
• The configuration is launched.

OR

• Navigate to and select the desired launch configuration file
• Press “Run” or “Debug”
• The configuration is launched.

Sharing a configuration

• Launch configurations are local by default.
• From the Run or Debug drop down menu, select "Run..." or “Debug…”
• The Launch configuration dialog appears showing all configurations in the current project.
• Choose the desired configuration, and select the “Team” tab.
• De-select the “store configuration locally” check box.
• Press the “Save” button.
• The configuration will be added to the “.launches” folder, in the project folder (a “.launches” folder will be created if not already present. Note, launch configuration files have a “.launch” extension).
• Sharing the configuration now requires releasing the file into a team stream.

Making a local (non-shared) configuration

• Configurations are local by default.

Editing a local configuration

• Editing a local configuration is the same as editing a shared configuration
• Press Run or Debug.
• Double click the desired configuration in the Launch Configuration tree.
• The configuration is displayed in the tabbed pane.
• Modify any attributes and press “Save”.

Deleting a local configuration

• Select the desired configuration in the Launch Configuration dialog and press “Delete”.
• (Do we need a confirmation dialog?)

Making a shared configuration local

• From the Run or Debug drop down menu, select "Run..." or “Debug…”
• The Launch configuration dialog appears showing all configurations in the current project.
• Double click the desired configuration, and select the “Team” tab.
• Check the “store configuration locally” check box.
• Press the “Save” button.
• The configuration will be added to the local (metadata) .launches file, are removed from the workspace.
• When releasing to the stream, the configuration will appear as removed.

Renaming a local configuration

• Navigate to the configuration using the Launch Configuration dialog.
• Double click the desired configuration, to display its attributes in the tabbed pane area.
• Change the name in the “name” field and press “Save”.

Sharing a local configuration

• See “Sharing a configuration” above

Launching without context

• Nothing is selected in any navigator and there are no open editors
• Press Run or Debug
• The Launch Configuration dialog is displayed with no selected project.
• Select a project to populate the configurations list with the configurations in that project.

Launching without main context

• A compilation unit is selected in the navigator, or is open in the active editor. However, there is no "main" method in the compilation unit.
• Press Run or Debug
• The Launch Configuration dialog opens, with default values in the tabbed pane area for a Java Application. However, the “main” class field is empty.
• Pressing “Launch” results in an error dialog asking to “Specify a main method to run”.
• (We could also have the button disabled, with an info line in the dialog – not sure of the style to use here).

Launching a non-resource (main in external jar), via configuration

• Press Run/Debug.
• Create a new “Java Application” configuration.
• Select the check box labeled “Include Jars” below the “Browse” button for specifying a main class.
• A dialog will appear with all types containing main methods in the project and all jars referenced on its class path. A progress dialog appears as the search is being performed.

Favorites

• Select "Organize..." from the run/debug drop down menu
• A dialog appears displaying all launch configurations in the workspace (local and shared)
• A "favorites" list appears on the right hand side of the dialog, and is initially empty.
• Add selected configurations to the favorites list by pressing "Add to favorites".
• Remove selected configurations from the favorites list by pressing "Remove from favorites"
• Favorites appear in the drop down run and debug menus, above the usual launch history.

Notes

This provides the user with a way to define a set of favorite launch configurations. We could provide keyboard accelerators to launch then as well (i.e. numbers 1, 2, 3…). We can provide a “history size” preference as well.

Launchers that do not support configurations

Using this approach, there is no concept of a “launcher” – only configurations. If a launch configuration has no UI, it simply inherits the configuration pages that are applicable to all launch configurations – Sharing and Perspective pages. (For example, the PDE launcher is public, but currently has no UI. Using launch configurations, a PDE launch configuration would inherit the “Sharing” and “Perspective” pages/attributes.)

A launch configuration that is not public, does not have to be a launch configuration extension. (For example, the Scrapbook launcher needs only register a launch with the debug plug-in, it does not have to be defined as a launch configuration extension. Launches that do not have configurations cannot be added to the launch history.)

Programmatic Launching

Launching is performed programmatically, by invoking a configuration’s launch API. The set of all configurations is available from the launch manager.

Managing Launch Configuration Files

Using this approach, (shared) launch configurations are stored as individual files in the workspace. By default, they are all stored in a “.launches” folder. We can allow the user to move/rename these files via regular resource manipulation techniques. The debug plug-in will have to maintain an index of the files, and listen to resource deltas to update its index. This would allow an advanced user to manage the storage of configurations, and possibly store configurations in different folders.

 

Currently, this approach would not initially provide custom editors for launch configuration files. However, this feature could be added in the future.

Pros and Cons

Pros

• Easy centralized access to launch configurations (via launch configuration dialog)

• Launch configurations know how to launch themselves

• Shields the user from launch configuration file management responsibility
• Allows advanced users to manage launch configuration files
• Sharing with configurations with team uses standard file sharing mechanisms
• Single-click launch when a configuration is selected in the navigator
• Simple implementation of local configurations – all stored in a single file in the meta-data area (could also be stored as individual files)

Cons

• No single-click launch (unless a configuration is selected)

 

 

Copyright © 2001 Object Technology International, Inc.