platform-core-home/documents/scoped_builds.html

Revision 1.2 - (view) (download) (as text)

1 :	johna	1.1	<html>
2 :			<head>
3 :			<meta http-equiv="Content-Language" content="en-us">
4 :			<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
5 :			<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
6 :			<meta name="ProgId" content="FrontPage.Editor.Document">
7 :			<title>Eclipse Build Story</title>
8 :			</head>
9 :
10 :			<body>
11 :
12 :			<h1>Improving the Eclipse Build Story</h1>
13 :			<p>Last modified March 22, 2004</p>
14 :			<h2>References</h2>
15 :			<ul>
16 :			<li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=50816">50816</a> - [plan item] Make workspace builds more scalable</li>
17 :			<li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">53565</a> - Improve manual builds</li>
18 :			<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>
19 :			<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>
20 :			</ul>
21 :			<h2>The Status Quo (2.1 and 3.0M7)</h2>
22 :			<p>Build-related items show up in 2 places in the UI:</p>
23 :			<ul>
24 :			<li><b>Project</b> menu
25 :			<ul>
26 :			<li><b>Build Project</b>
27 :			(only appears when auto-build is off)</li>
28 :			<li><b>Rebuild Project</b></li>
29 :			<li><b>Build All (Ctrl+B)</b>
30 :			(only appears when auto-build is off)</li>
31 :			<li><b>Rebuild All</b>
32 :			</li>
33 :			</ul>
34 :			</li>
35 :			<li>Context menu on project selections
36 :			<ul>
37 :			<li><b>Build Project</b>
38 :			(only when auto-build is off)</li>
39 :			</ul>
40 :			</li>
41 :			</ul>
42 :			<p>Semantics:</p>
43 :			<ul>
44 :			<li><b>Project > Build Project</b>
45 :			<ul>
46 :			<li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on just the
47 :			selected project(s)</li>
48 :			<li>does not build out-of-date prerequisite projects</li>
49 :			<li>fails if there are prerequisite projects with no recorded build state</li>
50 :			</ul>
51 :			</li>
52 :			<li><b>Project > Rebuild Project</b>
53 :			<ul>
54 :			<li>calls <code>IProject.build(FULL)</code> on just the selected project(s)</li>
55 :			<li>does not build out-of-date prerequisite projects</li>
56 :			<li>fails if there are prerequisite projects with no recorded build state</li>
57 :			</ul>
58 :			</li>
59 :			<li><b>Project > Build </b><b>All</b>
60 :			<ul>
61 :			<li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li>
62 :			</ul>
63 :			</li>
64 :			<li><b>Project > Rebuild </b><b>All</b>
65 :			<ul>
66 :			<li>calls <code>IWorkspace.build(FULL_BUILD)</code></li>
67 :			</ul>
68 :			</li>
69 :			<li>Content menu <b>Build Project</b>
70 :			<ul>
71 :			<li>Same as <b>Project > Build Project</b></li>
72 :			</ul>
73 :			</li>
74 :			</ul>
75 :			<p>Observations:</p>
76 :			<ul>
77 :			<li><b>Build Project</b> is quite unhelpful; it often produces useless
78 :			results or fails outright</li>
79 :			<li>When auto-build is on, <b>Rebuild Project</b> calls <code>IProject.build(FULL)</code>
80 :			on just the selected project(s) and does not follow-up with auto-building
81 :			the downstream projects, leaving the workspace in a less-than-fully-built
82 :			state. The next change the user makes will trigger building all downstream
83 :			projects (this behavior has been fixed in 3.0 stream).</li>
84 :			<li>It is anomalous to be removing menu items rather than disabling them when
85 :			auto-build is off</li>
86 :			<li>There is frequent user confusion about the difference between <b>Build</b>
87 :			and <b>Rebuild</b>.</li>
88 :			<li>Users with very large, highly interdependent projects face long build delays
89 :			when building the entire workspace and would like to build smaller
90 :			portions of the workspace more easily.</li>
91 :			</ul>
92 :			<h2>Proposed Improvements for 3.0</h2>
93 :			<p>We propose to make the build story more useful by providing "targeted
94 :			builds" which have the flavor of make (or Ant) builds where the user says
95 :			what projects they want to end up with in a "built" state and letting
96 :			the system figure out what set of prerequisite projects need to be taken into
97 :			account. By allowing the user to tell us which project(s) are important to them,
98 :			we give them a powerful tool to control how much work gets done when they say
99 :			"build". (This proposal only affects manual builds; it does not change
100 :			the way auto-build mode works.)</p>
101 :			<p>Summary of proposed changes:</p>
102 :			<ul>
103 :			<li>Change semantics of <b>Build Project</b> command to build prerequisites if
104 :			required.</li>
105 :			<li>Replace <b>Rebuild Project</b> and <b>Rebuild All</b> commands with a <b>Clean</b>
106 :			command which discards internal build state and ensures that subsequent
107 :			the build will begin from scratch (same as old <b>Rebuild</b> behavior).</li>
108 :			<li>Add <b>Build Working Set</b> command that builds all projects in the
109 :			working set, and their prerequisites if required</li>
110 :			</ul>
111 :			<p>Build shows up in same 2 places in UI:</p>
112 :			<ul>
113 :			<li><b>Project</b> menu
114 :			<ul>
115 :			<li><b>Build Project</b>
116 :			(<i>disabled</i> when auto-build is on)</li>
117 :			<li><b>Build All (Ctrl+B)</b>                 (<i>disabled</i> when auto-build is on)
118 :			</li>
119 :			<li><b>Build Working Set
120 :			>
121 :			</b>(<i>disabled</i> when auto-build is on)
122 :			<ul>
123 :			<li><b>MRU list</b> of working sets with dot marking last-built one</li>
124 :			<li><b>Select Working Set...</b>  (<i>disabled</i> when auto-build is on)</li>
125 :			</ul>
126 :			</li>
127 :			<li><b>Clean...</b></li>
128 :			</ul>
129 :			</li>
130 :			<li>Context menu on project selections
131 :			<ul>
132 :			<li><b>Build Project</b>
133 :			(<i>disabled</i> when auto-build is on)</li>
134 :			</ul>
135 :			</li>
136 :			</ul>
137 :			<p>Semantics:</p>
138 :			<ul>
139 :			<li><b>Project > Build Project</b>
140 :			<ul>
141 :			<li>ensures that all selected projects are up-to-date build-wise</li>
142 :			<li>out-of-date prerequisite projects will be automatically brought
143 :			up-to-date</li>
144 :			<li>like <b>Project > Build Working Set > <i>working set</i></b> except no
145 :			working set is created</li>
146 :			<li>disabled when no projects are selected</li>
147 :			</ul>
148 :			</li>
149 :			<li><b>Project > Build All</b>
150 :			<ul>
151 :			<li>unchanged from 2.1</li>
152 :			<li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li>
153 :			<li>standard key binding Ctrl+B</li>
154 :			</ul>
155 :			</li>
156 :			<li><b>Project > Build Working Set > Select Working Set...</b>
157 :			<ul>
158 :			<li>Presents a dialog to choose a working set, possibly defining one
159 :			in the process. Successful exit causes the selected working set to become the
160 :			current working set and then be built (see next item)</li>
161 :			</ul>
162 :			</li>
163 :			<li><b>Project > Build Working Set > <i>working set</i></b>
164 :			<ul>
165 :			<li>ensures that all projects in working set are up-to-date build-wise</li>
166 :			<li>out-of-date prerequisite projects will be automatically brought
167 :			up-to-date</li>
168 :			<li>let C = transitive closure of working set under prerequisite relation</li>
169 :			<li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on each project
170 :			in C, but only if the project needs rebuilding</li>
171 :			<li>applies workspace-wide project build order to subset C to determine
172 :			build order</li>
173 :			</ul>
174 :			</li>
175 :			<li>A keybinding can be created for the command <b>Repeat Last Working Set Build</b>.
176 :			This command does not appear as a separate menu item, but is dynamically bound
177 :			to the working set in the MRU list that was most recently built.
178 :			</li>
179 :			<li><b>Project > Clean...</b>
180 :			<ul>
181 :			<li>Cleans up after previously run builders. Presents a dialog explaining a bit what
182 :			"clean" means, and radio buttons for "Clean all projects" and
183 :			"Clean selected projects". If the dialog is OKed, asks all builders to
184 :			forget build states and removes all problem markers from the workspace. The
185 :			next build will start from square one. If autobuild is turned on a build will be
186 :			kicked off immediately.</li>
187 :			</ul>
188 :			</li>
189 :			<li>Context menu <b>Build Project</b>
190 :			<ul>
191 :			<li>same as <b>Project > Build Project</b></li>
192 :			</ul>
193 :			</li>
194 :			</ul>
195 :			<h2>Explaining How Builds Work to Users</h2>
196 :			<p>Here's how we would explain it to users:</p>
197 :			You have two modes of working: <i>auto-build</i> mode and <i>manual build</i> mode.
198 :			By default, you are in auto-build mode and Eclipse takes care of compiling source
199 :			files automatically. Builds occur automatically in the background every time
200 :			you change files in the workspace (for example saving an editor).
201 :			Auto-build is convenient because it means problems view, binaries, etc. are are
202 :			up-to-date at all times. The downside is that in large workspaces auto-builds can be
203 :			time-consuming if you are changing files in projects with lots of downstream
204 :			dependent projects.
205 :			</p>
206 :			<p>
207 :			If auto-build is taking too long and is interfering with ongoing development, it can
208 :			be turned off. Once in manual build mode, the user is in complete control over
209 :			when builds occur and what gets built. <b>Project > Build All (Ctrl+B)</b>
210 :			can be invoked at any time to trigger what auto-build was doing automatically.
211 :			This allows you to build up a larger set of changes before invoking
212 :			a build (Eclipse remembers which files have changed so that it does not have to do
213 :			more work than required when you do ask for a build.
214 :			</p>
215 :			<p>
216 :			In large workspaces, building the entire workspace can take a long time if you
217 :			make changes with a significant impact on dependent projects. Often there are
218 :			only a few projects that really matter to you a a given time. You can now simply
219 :			select the project or projects that you want to bring up-to-date, and select
220 :			<b>Build Project</b> from the context menu or <b>Project</b> menu. This will
221 :			build only the selected projects, and any prerequisite projects that need to be
222 :			built in order to correctly build the selected projects. Projects that depend on the projects
223 :			you build will not be built. If you're familiar with the make tool, or Ant, they work
224 :			the same way.
225 :			</p>
226 :			<p>
227 :			If you're interested in a set of projects, you may find it inconvenient to
228 :			be repeatedly selecting several projects in the Navigator. In this case, you
229 :			can choose <b>Project > Build Working Set > Select Working Set... </b>and
230 :			choose a working set that contains the projects that you want to have built. This
231 :			has the exact same effect as selecting that set of projects in the Navigator and
232 :			selecting <b>Build Project</b>. Again, prerequisite projects will be built automatically
233 :			if necessary. Recently built working sets appear on the <b>Project > Build Working
234 :			Set ></b> submenu, making it fast to switch to any of these. You can allocate
235 :			a key binding for the command <b>Repeat Last Working Set Build</b> in the
236 :	johna	1.2	<b>Project</b> category of the <b>General > Keys</b> preference page,
237 :	johna	1.1	if you want a convient way to invoke a working set build.
238 :			</p>
239 :			<p>
240 :			Under normal circumstances, you should have no reason to use the <b>Clean</b>
241 :			command. Eclipse builders are generally incremental - they only build files that
242 :			have changed since the last build, or files that are affected by changed files.
243 :			This makes Eclipse builds very efficient even when there are large numbers of files.
244 :			If something goes wrong and Eclipse loses track of where it was, this incremental
245 :			process may fail to bring a project up to date. If this ever happens, the
246 :			<b>Clean</b> command is there so the user can manually intervene and set
247 :			Eclipse back on the tracks. This ensures that the next build will recompile all
248 :			files over from scratch, as if the builder was running for the very first time. Naturally,
249 :			this can be time consuming for large workspaces. You can selectively <b>Clean</b>
250 :			one or more projects if you know which projects are having problems building.
251 :			</p>
252 :			<h2>Implementation</h2>
253 :			<p>The proposed new behavior is included in the 3.0 M8 stable build. A
254 :			"Work in progress" preference page can be used to add back
255 :			the removed <b>Rebuild</b> menu actions. The new behavior has also
256 :			been packaged as a separate plug-in that can be run in Eclipse 2.1. Here
257 :			is how to use this prototype plug-in (id org.eclipse.ui.newbuild) in Eclipse 2.1:
258 :			<ul>
259 :			<li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">Get the plug-in</a>
260 :			from the bug report attachment.</li>
261 :			<li>Download the zip file.</li>
262 :			<li>Unzip it and drop the directory named org.eclipse.ui.newbuild into
263 :			your eclipse/plugins/ directory.</li>
264 :			<li>Delete the eclipse/.config subdirectory.</li>
265 :			<li>Customize your workbench perspective to enable the new build commands.
266 :			<b>Window > Customize Perspective</b>; <b>Commands</b> tab; check <b>New Build
267 :			Actions</b> item</li>
268 :			</ul>
269 :			</li>
270 :			<li><b>New Build Project</b>, <b>Build Working Set</b>, and <b>Clean </b>
271 :			now appear on the
272 :			Project menu.</li>
273 :			<li>The new Build Project now appears on the context menu for the selected
274 :			project labeled <b>New Build Project</b>.</li>
275 :			</ul>
276 :			<p>Comments and feedback are welcome in the bug report and on the
277 :			platform-core-dev mailing list.</p>
278 :			</body>
279 :			</html>

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3

Eclipse

platform-core-home/documents/scoped_builds.html