platform-core-home/documents/3.1/large_scale_builders.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (download) (as text) (annotate)
Wed Dec 22 22:13:50 2004 UTC (4 years, 11 months ago) by johna
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +59 -10 lines 
added description of solution

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Large-scale builder issues</title>
  <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<body text="#000000" bgcolor="#FFFFFF">

<table width="100%">
<tr><td style="background:#0080C0"><b><span style="color:white">Large-scale builder issues</span></b></td></tr>
</table>
<font size="-1">Last modified: December 22, 2004</font> 
<p>
The workspace builder infrastructure is designed primarily with efficient
incremental compilers in mind.  Eclipse exposes just two fundamental build
modes: auto-build and manual build.  This simplifies the user experience,
but is not sufficient when a workspace has a mixture of fast and slow builders,
and/or a mixture of small and large projects.  The working set build concept
introduced in Eclipse 3.0 improves the situation, but is still not flexible enough
in some cases.
</p>
<h3>Problem Overview</h3>
<p>
Eclipse-based builders currently provide a number of configuration options
that are not part of the platform builder infrastructure:
<ul>
<li>Each Ant builder instance allows the user to specify if the builder runs
on autobuild, manual build, clean build, or any combination thereof.</li>
<li>CDT provides a per-project setting to specify whether C builders respond
to autobuild ("Build on Resource Save").  This is turned off by default.</li>
<li>The external tools plug-in provides a property page that allows the user
to turn *any* builder on or off completely.</li>
</ul>
These approaches have some problems:
<ul>
<li>
	Out of the box, CDT projects cannot be built.  The workspace auto-build setting
	is on by default, which causes the manual build commands to be disabled in the UI.
	The per-project auto-build setting for C builders is off by default.  Thus there is 
	no UI command available to run them, except for the "Clean" command which is
	always available. This command is not appropriate because it requests that <b>all</b>
	builders discard their built state, preventing them from running incrementally on the
	next build.  If Ant builders are configured to not run on auto-build, they have the same problem.
</li><li>
	Both CDT and Ant builders have per-project auto-build settings, but the
	options have different names and are found in different places.  There is no cohesive
	user experience for these settings.
</li><li>
	Not all plug-ins behave well when they are disabled by the user.  Thus the external
	tool plug-in's "Builders" property page gives the user more control than it should.
</li>
</ul>
<p>
The platform needs to introduce more flexibility in how and when builders are
run. This support needs to have the following characteristics:
<ul>
<li>
	The end-user experience out of the box must continue to be simple. Autobuild
	should still be on by default when all existing builders are truly incremental,
	and manual build commands should be disabled.
</li>
<li>
	Flexibility must be controlled. Plug-ins that implement builders must be able
	to specify what kind of flexibility they want to expose to their users.  Builders
	should be able to specify what their out of box behaviour is.
</li>
<li>
	Flexibility, when available, must be presented consistently. The flexibility
	should also not be prominent since it is an advanced feature that shouldn't
	clutter and confuse the UI for basic users.
</li>
<li>
	Build commands in the Project menu and Navigator context menu should
	be available only when appropriate.  Build All should be enabled when
	there are one or more builders in the workspace that do not respond to
	automatic build but do respond to manual builds. Build Project should only be
	available when one or more projects in the current selection has that characteristic.
</li>
</ul>
<h3>Proposed Solution</h3>
<p>
The builders extension point will introduce an "isConfigurable" attribute that 
specifies whether a builder allows configuration of what build triggers it responds
to. Here is an example of a builder definition using this new attribute:
<pre>
  &lt;extension point="org.eclipse.core.resources.builders" id="flexbuilder" name="Flexible Builder"&gt;
    &lt;builder <b>isConfigurable="true"</b>&gt;
      &lt;run class="org.eclipse.core.tests.internal.builders.FlexibleBuilder"/&gt;
    &lt;/builder&gt;
  &lt;/extension&gt;
</pre>
Builders that don't specify this attribute will never be configurable.
<p>
For configurable builders, new API on <tt>ICommand</tt> will allow a client
to programmatically specify what triggers that command responds to.  The new
methods on <tt>ICommand</tt> are:
<ul>
<li><tt><b>isConfigurable</b>()</tt> - returns the value of the <tt>isConfigurable</tt> attribute
in the builder extension definition.</li>
<li><tt><b>isBuilding</b>(int trigger)</tt> - Indicates if a build command is currently
responding to a given build trigger.  Triggers are represented by the
<tt>IncrementalProjectBuilder.*_BUILD</tt> constants.</li>
<li><tt><b>setBuilding</b>(int trigger, boolean value)</tt> - Changes whether a build
command responds to a given build trigger.  This method has no effect for builders
that are not configurable.</li>
</ul>
<p>
When a builder's triggers are configured, the result will be persisted in the
<tt>.project</tt> file. This allows sharing of the custom build triggers with
other team members. Here is an example of the build spec from a project description 
file with a builder that does not respond to the autobuild trigger.  The new
<tt>triggers</tt> element specifies the active triggers for the command:
<pre>
  &lt;buildSpec&gt;
    &lt;buildCommand&gt;
      &lt;name&gt;org.eclipse.core.tests.resources.flexbuilder&lt;/name&gt;
      <b>&lt;triggers&gt;incremental,clean,full&lt;/triggers&gt;</b>
      &lt;arguments&gt;
      &lt;/arguments&gt;
    &lt;/buildCommand&gt;
  &lt;/buildSpec&gt;
</pre>
<p>
The build infrastructure will consult the build command each time build API is called 
(<tt>IWorkspace.build</tt> and <tt>IProject.build</tt>).  Builders will not be 
called on build triggers that they are configured to not respond to.
<p>
The UI build actions will use the <tt>isBuilding</tt> method to determine
whether various build commands are enabled for a particular selection.  For example,
if the selected project responds to the incremental build trigger, but not the
autobuild trigger, then the <b>Build Project</b> command will remain enabled
even when autobuild is turned on.  This will allow the user to manually trigger "non-incremental"
builders that are too slow to efficiently respond to the autobuild trigger, but allow
autobuild to continue triggering other builders in the workspace.
<p>
<h3>References</h3>
Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=60803">60803</a>.
</p>
</body>
</html>