Improving the Eclipse Build Story

Last modified March 22, 2004

References

The Status Quo (2.1 and 3.0M7)

Build-related items show up in 2 places in the UI:

Semantics:

Observations:

Proposed Improvements for 3.0

We propose to make the build story more useful by providing "targeted builds" which have the flavor of make (or Ant) builds where the user says what projects they want to end up with in a "built" state and letting the system figure out what set of prerequisite projects need to be taken into account. By allowing the user to tell us which project(s) are important to them, we give them a powerful tool to control how much work gets done when they say "build". (This proposal only affects manual builds; it does not change the way auto-build mode works.)

Summary of proposed changes:

Build shows up in same 2 places in UI:

Semantics:

Explaining How Builds Work to Users

Here's how we would explain it to users:

You have two modes of working: auto-build mode and manual build mode. By default, you are in auto-build mode and Eclipse takes care of compiling source files automatically. Builds occur automatically in the background every time you change files in the workspace (for example saving an editor). Auto-build is convenient because it means problems view, binaries, etc. are are up-to-date at all times. The downside is that in large workspaces auto-builds can be time-consuming if you are changing files in projects with lots of downstream dependent projects.

If auto-build is taking too long and is interfering with ongoing development, it can be turned off. Once in manual build mode, the user is in complete control over when builds occur and what gets built. Project > Build All (Ctrl+B) can be invoked at any time to trigger what auto-build was doing automatically. This allows you to build up a larger set of changes before invoking a build (Eclipse remembers which files have changed so that it does not have to do more work than required when you do ask for a build.

In large workspaces, building the entire workspace can take a long time if you make changes with a significant impact on dependent projects. Often there are only a few projects that really matter to you a a given time. You can now simply select the project or projects that you want to bring up-to-date, and select Build Project from the context menu or Project menu. This will build only the selected projects, and any prerequisite projects that need to be built in order to correctly build the selected projects. Projects that depend on the projects you build will not be built. If you're familiar with the make tool, or Ant, they work the same way.

If you're interested in a set of projects, you may find it inconvenient to be repeatedly selecting several projects in the Navigator. In this case, you can choose Project > Build Working Set > Select Working Set... and choose a working set that contains the projects that you want to have built. This has the exact same effect as selecting that set of projects in the Navigator and selecting Build Project. Again, prerequisite projects will be built automatically if necessary. Recently built working sets appear on the Project > Build Working Set > submenu, making it fast to switch to any of these. You can allocate a key binding for the command Repeat Last Working Set Build in the Project category of the General > Keys preference page, if you want a convient way to invoke a working set build.

Under normal circumstances, you should have no reason to use the Clean command. Eclipse builders are generally incremental - they only build files that have changed since the last build, or files that are affected by changed files. This makes Eclipse builds very efficient even when there are large numbers of files. If something goes wrong and Eclipse loses track of where it was, this incremental process may fail to bring a project up to date. If this ever happens, the Clean command is there so the user can manually intervene and set Eclipse back on the tracks. This ensures that the next build will recompile all files over from scratch, as if the builder was running for the very first time. Naturally, this can be time consuming for large workspaces. You can selectively Clean one or more projects if you know which projects are having problems building.

Implementation

The proposed new behavior is included in the 3.0 M8 stable build. A "Work in progress" preference page can be used to add back the removed Rebuild menu actions. The new behavior has also been packaged as a separate plug-in that can be run in Eclipse 2.1. Here is how to use this prototype plug-in (id org.eclipse.ui.newbuild) in Eclipse 2.1:

  • New Build Project, Build Working Set, and Clean  now appear on the Project menu.
  • The new Build Project now appears on the context menu for the selected project labeled New Build Project.

    • Comments and feedback are welcome in the bug report and on the platform-core-dev mailing list.