platform-core/documents/3.1/large_scale_builders.html - www.eclipse.org/eclipse - Git at Google

 <!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>
	<!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>
	<extension point="org.eclipse.core.resources.builders" id="flexbuilder" name="Flexible Builder">
	<builder <b>isConfigurable="true"</b>>
	<run class="org.eclipse.core.tests.internal.builders.FlexibleBuilder"/>
	</builder>
	</extension>
	</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>
	<buildSpec>
	<buildCommand>
	<name>org.eclipse.core.tests.resources.flexbuilder</name>
	<b><triggers>incremental,clean,full</triggers></b>
	<arguments>
	</arguments>
	</buildCommand>
	</buildSpec>
	</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>