Summary
This article discusses two central mechanisms that are associated with projects
in an Eclipse workspace. The first of these is incremental project builders,
which create some built state based on the project contents, and then keep that
built state synchronized as the project contents change. The second is project
natures, which define and manage the association between a given project and
a particular plug-in or feature. The purpose and uses of builders and natures
will be described in detail, and working examples will be provided to highlight
the finer details of implementing them for your own plug-in. This article is
intended to supplement, rather than replace, the documentation on builders and
natures found in the Eclipse Platform Plug-in Developer Guide.
By John Arthorne, IBM OTI Labs
January 27, 2003
Updated November 23, 2004 for Eclipse 3.0
Builder resource deltas are rooted at a single project. A builder can
request deltas for multiple projects, but each resource delta returned by
IncrementalProjectBuilder.getDelta has a single project
as its root.
Some resource change information that is available to resource change
listeners is omitted from build deltas. In particular, changes to resource
markers (IResourceDelta.MARKERS), and changes to synchronization
information (IResourceDelta.SYNC) are not included in builder
deltas. These change types are omitted for performance reasons, since this
information is not typically of interest to builders.
Builder deltas may be null. If a builder has never been invoked before,
any request for deltas will return null. Also, if a builder is not run for
a long time, the platform reserves the right to return a null delta. This
is done because keeping track of resource changes over an extended period
of time can be very costly, and it's generally more efficient to just rebuild
from scratch if the builder hasn't been run in a long time. When a builder
receives a null delta, it should just discard all existing built state, and
resort to doing a full build.
Auto-build
From the point of view of the builder implementation, auto-build is exactly
the same as incremental build. The difference with auto-build is that
it is not triggered by an explicit build request, but as an automatic side
effect of resources changes in the workspace. When auto-build is turned
on, all installed builders will be invoked every time resources are added,
removed, or modified in the eclipse workspace. There is no guarantee about
precisely when auto-build will occur in relation to the operation that modified the
workspace. The build generally occurs in a background thread a short time after
all threads have stopped modifying the workspace. If a thread attempts to modify
the workspace while the build is running, the build is halted and the thread is allowed
to proceed with its changes. Auto-build will continue to attempt running until it
has sufficient time to complete the entire workspace build. As with resource change
events, you can avoid frequent auto-builds by wrapping long running operations in
an IWorkspaceRunnable passed to IWorkspace.run, or using
a WorkspaceJob.
There is a preference in the Eclipse workbench
for turning auto-build on or off (Preferences > Workbench > Build automatically).
Auto-build can also be turned on or off programatically by setting the auto-build flag
in the workspace description, although this is not generally recommended. The
following code snippet turns auto-build on:
When a full build is invoked, it is a request to discard all existing
built state and start over from scratch. There is currently no command
in the Eclipse workbench that allows a user to directly invoke a full build.
The first build after invoking clean will cause a full build in the cleaned projects.
Theoretically, full build should never be needed if your incremental build is
clever enough. However, if your builder is for some reason unable to correctly
build incrementally, it is useful to have an escape route available to rebuild
everything from scratch.
Clean build
The final variety of build, introduced in Eclipse 3.0, is clean. Clean
is inspired by the Unix make utility convention of using a target called clean
to discard all artifacts produced by a build. As with full build, clean should not
be required if all builders correctly perform their incremental builds. Clean is
intended largely as a safety blanket for the end user when things seem to go wrong
with their build process. Builders should implement clean by deleting all output
files produced by the build, and removing any problem markers associated with
that builder. Unlike other build types, the clean build is not implemented by the
build method on IncrementalProjectBuilder. For backwards
compatibility, there is a new clean method with an empty default implementation,
allowing older builders to continue running without modification.
The following is an example of a clean
implementation that just deletes all markers of a particular type from the project:
The build method on IncrementalProjectBuilder
takes as parameter an instance of IProgressMonitor. This object
should be used for reporting feedback and progress information to the user
as the build proceeds. The most important methods on IProgressMonitor
are beginTask, subTask, worked, and
done. The important concepts to remember about reporting progress
are:
In Eclipse 3.0, auto-build was moved into a background thread. In a GUI environment,
this allows the user to continue working as the build progresses. However, if
the user attempts to make further resources changes while the build is running,
auto-build needs to interrupt itself. The workspace checks for this kind of interruption
immediately before calling each individual builder. If the contention occurs while
a builder is running, the user's activity will typically be blocked until the currently
executing builder completes. While this is fine for relatively quick builders, it can
become frustrating for users when a single builder takes a very long time to complete.
To alleviate this, long running builders can check for interruption periodically during
their execution. The method isInterrupted on IncrementalProjectBuilder
will return true if another thread is waiting to modify the workspace. When
this happens, a builder can chose to abort the build and allow the other operation to
proceed. Note that interruption should not always be treated the same as cancelation,
since it occurs implicitly, rather than based on an explicit cancelation request by the
user. It is acceptable to respond to cancelation by discarding build state and resorting
to a full build on the next builder invocation, but this is too drastic for interruption.
Interruption should not cause significant additional overhead for subsequent builds.
Builders that cannot gracefully handle interruption should not respond to it at all.
The fact that auto-build occurs in a background thread can sometimes introduce
challenges for code that relies on builder output. In a headless batch environment,
you cannot simply modify resources and assume auto-build will occur
immediately. Headless tools that previously made this assumption might exit from
their main thread of execution while the background build is still running. The best
solution in this situation is to simply turn off auto-build, and maintain complete control
over when builds occur by explicitly invoking IWorkspace.build if and when
required. There are other situations where a plug-in wants to allow auto-build to run,
but needs to wait until it completes before proceeding. For example, when the user
attempts to launch a Java program they have just created or modified, the launch
needs to wait until auto-build completes to ensure that the correct class files are
used. In this situation, the background build job can be joined using the following code:
The join invocation will block until the auto-build job completes, or until
the join is interrupted or canceled. You can report progress while waiting by passing
a progress monitor to the join method. Manual incremental build jobs can be joined
in a similar manner using the ResourcesPlugin.FAMILY_MANUAL_BUILD job family.
Sidebar: the Java builder
The concept of automatic incremental compilation is not familiar to many developers.
A very frequent question from Eclipse beginners is, "where is the compile button?"
The answer is that an IDE with automatic compilation doesn't need a compile button. Every
time you make a change to a file, or a group of files, the incremental builder immediately rebuilds
every source file that was affected by the change. In this environment, the idea of compilation
as a task the user is involved in disappears -- the world is just always in a compiled state.
So what magic goes on behind the scenes to make this happen? How does the Java™ builder
know which files need to be recompiled when a given source file changes? This is no easy task,
but in broad brush strokes, this is what the Eclipse Java builder does:
The builder maintains a built state that includes a list of all types (classes or
interfaces) that are referenced by each type in the workspace. This information is returned
by the compiler each time a source file is compiled. This state is computed from scratch
on a full build, and updated incrementally on each subsequent build.
Whenever files are modified, the builder receives a resource delta that describes
which files were added, removed, or changed.
For deleted Java source files, the corresponding class files are deleted. Added and changed
source files are added to a queue of files that need to be compiled.
The builder then processes this queue as follows:
Remove a file from the queue, and compile it.
Compare the resulting type to the old class file, and see if the
type has structural changes. Structural changes are changes that can affect
the compilation of a referencing type: added or removed methods, fields or types, or changed method
signatures.
If the type has structural changes, find all types in the project that reference the changed type,
and add them to the queue.
If the type has changed at all, write it to disk in the builder's output folder.
Update the built state with the new reference information for the compiled type.
Repeat until the queue is empty.
As a final step, the builder generates problem markers for each compiled type that had
compilation problems.
The critical feature of the Java builder is that it is very fast 95% of the
time. Most times you edit a Java file, you don't make any structural changes.
This means the builder just has to compile that single file, and it's
done. When a type does have structural changes, all types that reference
it will be recompiled. However, those secondary types will almost never
have structural changes themselves, so the builder loop finishes with
at most a couple of iterations. On rare occasions, there will be significant
structure changes that cause many files to be recompiled. There is a lesson
here that you can apply when writing your own incremental builder. If
you can make your builder extremely fast for the most common cases, users
will generally tolerate a longer delay for those rare corner cases when
they come along.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or
both.