[platform-ant-dev] External tools and Ant UI

[Jared Burns <jared-eclipse@xxxxxxxxx>]

Attached is a document (in HTML and plain text) I'm working on that explains 
where I'd like to go with Eclipse's external tools and Ant integration. I'd 
appreciate any and all feedback.

Thanks,
- Jared

 
October 28, 2002

 
This document explains our plan for the future of Eclipse's external tools support. It explains how external tools are configured and executed, how external tools are used as project builders, and what our plans are for integrating the external tools support with the debugger.
For the purposes of this document, Ant scripts are considered a kind of external tool.

Debug Integration

 
Launch configurations

 
External tools will be created, run, and edited via the launch configuration framework.
We may add support to the launch configuration framework to open the launch configuration on an individual config or an arbitrary group of configs. Alternatively, this support would be added in the external tools UI.
We may add the notion of "workspace variables" to the launch configuration framework. This code currently exists in the external tools framework, but we believe it would make sense in the launch config framework and thus plan to push it down. This feature should improve our shared launch configuration story.

 
Debug view

 
When an external tool is run, it will appear in the debug view. We may provide the ability to terminate running tools from this view.
If we add the ability to debug Ant scripts (probably not for 2.1), that would also be done in this view.

 
Console view

 
When an external tool is run, its output will appear in the debug console view. The output displayed in the console will follow the users selection in the debug view as it does today for Java applications.
The debugger console will add new APIs to allow clients to append data from arbitrary streams and to allow clients to provide their own document provider to color output from those streams. More detail on this proposal can be found in Darin Wright's post to the platform-ant-dev mailing list.
We also plan to support navigation from Ant output in the console to the relevant editor location.

Managing External Tools

 
Creating external tools

 
External tools are created via the launch configuration dialog. They will thus inherit all launch configuration features including duplication, launch history, and sharing.

 
Running external tools

 
External tools can be run via the launch configuration dialog or via the external tools history.
In addition to the external tool running support, there will be an action on XML files that allows the user to run the file as an Ant script ("Run Ant...").
If a launch config already exists for the script, it will be run in its currently configured state. If no config exists for the script, the launch configuration dialog will appear, primed to create a new Ant configuration on the selected file.
Additionally, we will provide an Ant view (based on Roscoe Rush's Ant View) that will allow the user to execute entire scripts or targets.

 
External tools history

 
The external tools history will appear on its own menu, as it does today.
If we add support for debugging external tools (Ant scripts in particular), tools launched in debug mode will appear in the debug history.
This separation is intended to keep the notions of using external tools and developing external tools distinct.

Editing Ant scripts

 
Editing build.xml files

 
We will provide a lightweight XML editor for build.xml Ant scripts (based on Alf Schiefelbein's  Planty) that provides syntax highlighting and code assist.
We will provide an outline page associated with the editor for navigating to targets, tasks, etc.

Project Builders

 
Creating builders

 
External tool project builders are added to projects by either creating a new launch configuration or copying an existing configuration.

 
Editing builders

 
External tool project builders are edited with a modified version of the launch configuration dialog which shows the tabs for exactly one configuration.

 
Storing builders

 
External tool project builders are stored by translating a launch configuration into an ICommand.

 
Running builders

 
External tool project builders are run by translating ICommands into launch configurations and running them.

Title: External Tools UI

	October 28, 2002
	This document explains our plan for the future of Eclipse's external tools support. It explains how external tools are configured and executed, how external tools are used as project builders, and what our plans are for integrating the external tools support with the debugger. For the purposes of this document, Ant scripts are considered a kind of external tool.
Debug Integration
	Launch configurations
	External tools will be created, run, and edited via the launch configuration framework. We may add support to the launch configuration framework to open the launch configuration on an individual config or an arbitrary group of configs. Alternatively, this support would be added in the external tools UI. We may add the notion of "workspace variables" to the launch configuration framework. This code currently exists in the external tools framework, but we believe it would make sense in the launch config framework and thus plan to push it down. This feature should improve our shared launch configuration story.
	Debug view
	When an external tool is run, it will appear in the debug view. We may provide the ability to terminate running tools from this view. If we add the ability to debug Ant scripts (probably not for 2.1), that would also be done in this view.
	Console view
	When an external tool is run, its output will appear in the debug console view. The output displayed in the console will follow the users selection in the debug view as it does today for Java applications. The debugger console will add new APIs to allow clients to append data from arbitrary streams and to allow clients to provide their own document provider to color output from those streams. More detail on this proposal can be found in Darin Wright's post to the platform-ant-dev mailing list. We also plan to support navigation from Ant output in the console to the relevant editor location.
Managing External Tools
	Creating external tools
	External tools are created via the launch configuration dialog. They will thus inherit all launch configuration features including duplication, launch history, and sharing.
	Running external tools
	External tools can be run via the launch configuration dialog or via the external tools history. In addition to the external tool running support, there will be an action on XML files that allows the user to run the file as an Ant script ("Run Ant..."). If a launch config already exists for the script, it will be run in its currently configured state. If no config exists for the script, the launch configuration dialog will appear, primed to create a new Ant configuration on the selected file. Additionally, we will provide an Ant view (based on Roscoe Rush's Ant View) that will allow the user to execute entire scripts or targets.
	External tools history
	The external tools history will appear on its own menu, as it does today. If we add support for debugging external tools (Ant scripts in particular), tools launched in debug mode will appear in the debug history. This separation is intended to keep the notions of using external tools and developing external tools distinct.
Editing Ant scripts
	Editing build.xml files
	We will provide a lightweight XML editor for build.xml Ant scripts (based on Alf Schiefelbein's Planty) that provides syntax highlighting and code assist. We will provide an outline page associated with the editor for navigating to targets, tasks, etc.
Project Builders
	Creating builders
	External tool project builders are added to projects by either creating a new launch configuration or copying an existing configuration.
	Editing builders
	External tool project builders are edited with a modified version of the launch configuration dialog which shows the tabs for exactly one configuration.
	Storing builders
	External tool project builders are stored by translating a launch configuration into an ICommand.
	Running builders
	External tool project builders are run by translating ICommands into launch configurations and running them.