| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
| <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> |
| <meta name="ProgId" content="FrontPage.Editor.Document"> |
| <title>Eclipse Build Story</title> |
| </head> |
| |
| <body> |
| |
| <h1>Improving the Eclipse Build Story</h1> |
| <p>Last modified March 22, 2004</p> |
| <h2>References</h2> |
| <ul> |
| <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=50816">50816</a> - [plan item] Make workspace builds more scalable</li> |
| <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">53565</a> - Improve manual builds</li> |
| <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=46039">46039</a> - [Workbench] Rebuild project when autobuild is on is misleading</li> |
| <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/eclipse3_builder_issues.html">Eclipse 3.0 Build Infrastructure</a></li> |
| </ul> |
| <h2>The Status Quo (2.1 and 3.0M7)</h2> |
| <p>Build-related items show up in 2 places in the UI:</p> |
| <ul> |
| <li><b>Project</b> menu |
| <ul> |
| <li><b>Build Project</b> |
| (only appears when auto-build is off)</li> |
| <li><b>Rebuild Project</b></li> |
| <li><b>Build All (Ctrl+B)</b> |
| (only appears when auto-build is off)</li> |
| <li><b>Rebuild All</b> |
| </li> |
| </ul> |
| </li> |
| <li>Context menu on project selections |
| <ul> |
| <li><b>Build Project</b> |
| (only when auto-build is off)</li> |
| </ul> |
| </li> |
| </ul> |
| <p>Semantics:</p> |
| <ul> |
| <li><b>Project > Build Project</b> |
| <ul> |
| <li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on just the |
| selected project(s)</li> |
| <li>does not build out-of-date prerequisite projects</li> |
| <li>fails if there are prerequisite projects with no recorded build state</li> |
| </ul> |
| </li> |
| <li><b>Project > Rebuild Project</b> |
| <ul> |
| <li>calls <code>IProject.build(FULL)</code> on just the selected project(s)</li> |
| <li>does not build out-of-date prerequisite projects</li> |
| <li>fails if there are prerequisite projects with no recorded build state</li> |
| </ul> |
| </li> |
| <li><b>Project > Build </b><b>All</b> |
| <ul> |
| <li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li> |
| </ul> |
| </li> |
| <li><b>Project > Rebuild </b><b>All</b> |
| <ul> |
| <li>calls <code>IWorkspace.build(FULL_BUILD)</code></li> |
| </ul> |
| </li> |
| <li>Content menu <b>Build Project</b> |
| <ul> |
| <li>Same as <b>Project > Build Project</b></li> |
| </ul> |
| </li> |
| </ul> |
| <p>Observations:</p> |
| <ul> |
| <li><b>Build Project</b> is quite unhelpful; it often produces useless |
| results or fails outright</li> |
| <li>When auto-build is on, <b>Rebuild Project</b> calls <code>IProject.build(FULL)</code> |
| on just the selected project(s) and does not follow-up with auto-building |
| the downstream projects, leaving the workspace in a less-than-fully-built |
| state. The next change the user makes will trigger building all downstream |
| projects (this behavior has been fixed in 3.0 stream).</li> |
| <li>It is anomalous to be removing menu items rather than disabling them when |
| auto-build is off</li> |
| <li>There is frequent user confusion about the difference between <b>Build</b> |
| and <b>Rebuild</b>.</li> |
| <li>Users with very large, highly interdependent projects face long build delays |
| when building the entire workspace and would like to build smaller |
| portions of the workspace more easily.</li> |
| </ul> |
| <h2>Proposed Improvements for 3.0</h2> |
| <p>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.)</p> |
| <p>Summary of proposed changes:</p> |
| <ul> |
| <li>Change semantics of <b>Build Project</b> command to build prerequisites if |
| required.</li> |
| <li>Replace <b>Rebuild Project</b> and <b>Rebuild All</b> commands with a <b>Clean</b> |
| command which discards internal build state and ensures that subsequent |
| the build will begin from scratch (same as old <b>Rebuild</b> behavior).</li> |
| <li>Add <b>Build Working Set</b> command that builds all projects in the |
| working set, and their prerequisites if required</li> |
| </ul> |
| <p>Build shows up in same 2 places in UI:</p> |
| <ul> |
| <li><b>Project</b> menu |
| <ul> |
| <li><b>Build Project</b> |
| (<i>disabled</i> when auto-build is on)</li> |
| <li><b>Build All (Ctrl+B)</b> (<i>disabled</i> when auto-build is on) |
| </li> |
| <li><b>Build Working Set |
| > |
| </b>(<i>disabled</i> when auto-build is on) |
| <ul> |
| <li><b>MRU list</b> of working sets with dot marking last-built one</li> |
| <li><b>Select Working Set...</b> (<i>disabled</i> when auto-build is on)</li> |
| </ul> |
| </li> |
| <li><b>Clean...</b></li> |
| </ul> |
| </li> |
| <li>Context menu on project selections |
| <ul> |
| <li><b>Build Project</b> |
| (<i>disabled</i> when auto-build is on)</li> |
| </ul> |
| </li> |
| </ul> |
| <p>Semantics:</p> |
| <ul> |
| <li><b>Project > Build Project</b> |
| <ul> |
| <li>ensures that all selected projects are up-to-date build-wise</li> |
| <li>out-of-date prerequisite projects will be automatically brought |
| up-to-date</li> |
| <li>like <b>Project > Build Working Set > <i>working set</i></b> except no |
| working set is created</li> |
| <li>disabled when no projects are selected</li> |
| </ul> |
| </li> |
| <li><b>Project > Build All</b> |
| <ul> |
| <li>unchanged from 2.1</li> |
| <li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li> |
| <li>standard key binding Ctrl+B</li> |
| </ul> |
| </li> |
| <li><b>Project > Build Working Set > Select Working Set...</b> |
| <ul> |
| <li>Presents a dialog to choose a working set, possibly defining one |
| in the process. Successful exit causes the selected working set to become the |
| current working set and then be built (see next item)</li> |
| </ul> |
| </li> |
| <li><b>Project > Build Working Set > <i>working set</i></b> |
| <ul> |
| <li>ensures that all projects in working set are up-to-date build-wise</li> |
| <li>out-of-date prerequisite projects will be automatically brought |
| up-to-date</li> |
| <li>let C = transitive closure of working set under prerequisite relation</li> |
| <li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on each project |
| in C, but only if the project needs rebuilding</li> |
| <li>applies workspace-wide project build order to subset C to determine |
| build order</li> |
| </ul> |
| </li> |
| <li>A keybinding can be created for the command <b>Repeat Last Working Set Build</b>. |
| This command does not appear as a separate menu item, but is dynamically bound |
| to the working set in the MRU list that was most recently built. |
| </li> |
| <li><b>Project > Clean...</b> |
| <ul> |
| <li>Cleans up after previously run builders. Presents a dialog explaining a bit what |
| "clean" means, and radio buttons for "Clean all projects" and |
| "Clean selected projects". If the dialog is OKed, asks all builders to |
| forget build states and removes all problem markers from the workspace. The |
| next build will start from square one. If autobuild is turned on a build will be |
| kicked off immediately.</li> |
| </ul> |
| </li> |
| <li>Context menu <b>Build Project</b> |
| <ul> |
| <li>same as <b>Project > Build Project</b></li> |
| </ul> |
| </li> |
| </ul> |
| <h2>Explaining How Builds Work to Users</h2> |
| <p>Here's how we would explain it to users:</p> |
| You have two modes of working: <i>auto-build</i> mode and <i>manual build</i> 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. |
| </p> |
| <p> |
| 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. <b>Project > Build All (Ctrl+B)</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. |
| </p> |
| <p> |
| 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 |
| <b>Build Project</b> from the context menu or <b>Project</b> 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. |
| </p> |
| <p> |
| 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 <b>Project > Build Working Set > Select Working Set... </b>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 <b>Build Project</b>. Again, prerequisite projects will be built automatically |
| if necessary. Recently built working sets appear on the <b>Project > Build Working |
| Set ></b> submenu, making it fast to switch to any of these. You can allocate |
| a key binding for the command <b>Repeat Last Working Set Build</b> in the |
| <b>Project</b> category of the <b>General > Keys</b> preference page, |
| if you want a convient way to invoke a working set build. |
| </p> |
| <p> |
| Under normal circumstances, you should have no reason to use the <b>Clean</b> |
| 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 |
| <b>Clean</b> 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 <b>Clean</b> |
| one or more projects if you know which projects are having problems building. |
| </p> |
| <h2>Implementation</h2> |
| <p>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 <b>Rebuild</b> 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: |
| <ul> |
| <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">Get the plug-in</a> |
| from the bug report attachment.</li> |
| <li>Download the zip file.</li> |
| <li>Unzip it and drop the directory named org.eclipse.ui.newbuild into |
| your eclipse/plugins/ directory.</li> |
| <li>Delete the eclipse/.config subdirectory.</li> |
| <li>Customize your workbench perspective to enable the new build commands. |
| <b>Window > Customize Perspective</b>; <b>Commands</b> tab; check <b>New Build |
| Actions</b> item</li> |
| </ul> |
| </li> |
| <li><b>New Build Project</b>, <b>Build Working Set</b>, and <b>Clean </b> |
| now appear on the |
| Project menu.</li> |
| <li>The new Build Project now appears on the context menu for the selected |
| project labeled <b>New Build Project</b>.</li> |
| </ul> |
| <p>Comments and feedback are welcome in the bug report and on the |
| platform-core-dev mailing list.</p> |
| </body> |
| </html> |
