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 JREs 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 projects .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 JREs 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 projects .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
configurations 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.
|