Improved Build Story

Last revised 17:15 Thursday February 14, 2002

This proposal covers a series of additions and changes to Eclipse to improve the build story and provider better Ant integration.


Running existing Ant scripts inside Eclipse

Part of the perceived value of Eclipse's Ant support is that the Ant scripts written outside Eclipse can be run without modification within Eclipse. This is crucial if Eclipse is to attract open source developers working with existing code bases and Ant scripts.

This is not well supported in Eclipse 1.0. The problem is that Eclipse Ant assumes tight integration with Eclipse, with all that entails. Some of things that don't work well:

As a general goal, we need to find ways to make Eclipse Ant support these developers. Here are some general properties that the solution should have:

If it is easy to run inside Eclipse Ant scripts written for a non-Eclipse environment, the converse follows automatically: developers working in Eclipse should be able to write and run scripts that they intend to also use outside Eclipse. Obviously, these scripts should avoid Eclipse-specific Ant tasks, which are not available outside Eclipse. While Eclipse Ant should provide added value for Eclipse users, we should avoid doing things that gratuitously lock users into Eclipse. 

Using Ant's "if" or "unless" clause makes it quite easy to conditionalize scripts so that they work both inside and outside Eclipse. All that is required is a single well known variable that is given some value when Ant is run inside Eclipse.

The proposed changes to Eclipse Ant are as follows:

The "refresh" problem

The following problem becomes painfully apparent when an Ant script written to run outside Eclipse is run from inside Eclipse. The norm for an Ant script is to process some files and create, overwrite, or delete others. For an Eclipse user, there is a good chance that the files in question are somewhere in the workspace. The problem is that the Eclipse workspace has no way of knowing where in the workspace the affected files might be. Without further information, a refresh local on the entire workspace would be needed to ensure that the in-memory resource tree accurately reflects the local file system. This is a very bad situation. Refreshing the entire workspace is time-consuming (at least 0.2 ms per file). But if it is not done automatically, the user would have to worry about it and handle it manually. The user may have more knowledge that would allow them to refresh more selectively --- but it would still be their responsiblity to do it.

By its nature, the refresh operation modifies the resource tree. Modifying the resource tree triggers resource change event notifications. And if auto-build is turned on, resource tree modifications also triggers incremental project builders. Thus even a simple thing like refresh can have far-reaching consequences.

Here are three options for dealing with this:

We plan to support the first and second options, and pursue the third option as a separate work item.

Running Ant Scripts from the Workbench

In Eclipse 1.0, Ant has a very simple UI: The main user requirements are: The "Run..." action of the Windows Start menu is a simple UI that covers both use cases, and serves as a good model.

The proposal is to add a new item to the "Workbench" menu, called "Tool Script", which would bring up a Tool Scripts dialog. The Tool Scripts dialog would allow the user to specify the path of the Ant buildfile and command line arguments; the last N such commands would be remembered in a pulldown list.

[There are a couple of places in the Eclipse UI where similar kinds of things are done (e.g., Debug and Run pulldowns, search). The UI guidelines should recommend a style of presentation for these kinds of things; this would help fight a proliferation of different presentations, or similar presentations that are not similar enough.]

Additional properties:

Implementation details:

Other issues to be resolved:

Build Story

By the Eclipse build story we mean the mechanisms underlying the "Build" and "Rebuild all" actions that appear in the generic workbench UI.

Running Ant Scripts as Builders

A ordinary user would be unlikely to care which incremental builders a project has, or what order they run in. The user just hits "Build". These details are for the plug-in developer who provides the incremental project builders and the project natures which configure them.

However, we would like a way to give advanced user the ability to extend what happens when the user hits "Build".

The proposal is to allow the user to add additional Ant commands to the project's list of builders.

Ordering projects

When several projects are involved in a build, the individual projects get built, one at a time, in a certain order. Unless explicitly overridden by the user, the order of project is the default ordering of projects in the workspace as computed by Core using a topological sort based on project references (if project X refers to project Y then build Y before building X).

At the very least, we can improve the user experience by taking the following steps :

Ordering builders within a project

Particular incremental project builders are typically inserted in the project's build specification when it is configured to have a project nature (the code for the project nature does this). However, each project can be configured to have a number of project natures, in no particular order. At present, this mechanism is quite weak. How can a plug-in add a builder I after some other builder J when the project does not have a J? It is reminiscent of each program adding a line to the beginning (or end) of autoexec.bat when it gets installed, with no guarantee that things will work properly if you don't install the programs in the expected order.

Note that this is not the kind of question that we want to involve the user in. This is an internal matter for the plug-ins or project natures that are configuring a project. A reasonable solution therefore requires some scheme or mechanism so that plug-in can definitely resolve builder ordering issues.

In a separate work item, we are proposing to impose constraints on the order project natures get added to (or removed from) a project. For instance, if project nature B was known to have nature A as a prerequiste, then Core could arrange that a project to be configured with both A and B would get A first, then B. This would mean that the code for project nature B would be able to assume that A had already added its builders to the project. Consequently, A could determine where to add its builders to the project taking into account the positions of B's builders (assuming that A knows the ids of the builders that B adds).