e4 Changes

Flexible Project Structure in e4

Serge Beauchamp

While the Eclipse e4 project is currently placing on emphasis on strengthening the Eclipse platform as a generic application framework, Eclipse maintains its primary function as an integrated development environment.

In the past developers have had to deal with a lack of flexibility in the Eclipse IDE, when it comes to the requirements of complex development projects. In this article, E4-committer Serge Beauchamp discusses how e4 will bring more flexibility to the project management structure.

An IDE project consists of an organized set of files and their
meta information that can be used to achieve a particular task
(such as building an executable.)

Traditionally, C/C++ IDE projects have consisted fundamentally
of a simple list of files recorded hierarchically. C/C++ IDEs such
as Metrowerks CodeWarrior and Microsoft Visual Studio are a good
example of such an approach to working with projects.

But the Eclipse IDE was initially designed to support java
development, therefore its original project engine has different

In contrast with C based languages, in java there is a tighter
integration between the java classes and the source files that
contain them. In order for the java compiler to find the class
definitions, the source file typically has the same name as the
public class it contains, but more importantly java classes must be
located in source files that exist in file system directories which
have the same name as their package names.

The only flexibility with javac is to specify classpath
directives, but this does not alleviate the basic restriction of
having to keep java source files in directories according to their
package names.

So for Java developers, the source file organization is much
more rigid than in C based languages, where locating source files
is not an issue (all sources must be explicitly passed to the
compiler) and header files are either relative to the source files
themselves, or relative to given include paths. C/C++ developers
tend to host source files in a complex web of directories based on
many factors, including release engineering, componentization, team
cooperation, and development history.

Because of this directory/package-name restriction, Eclipse as a
java IDE did not need to support a very flexible project structure,
and in its early releases it simply displayed the straight
representation of the project directory on disk.

This design quickly became inadequate for using Eclipse as a
more general tool IDE, so many features were added over the years
to give Eclipse projects a more flexible project structure, such as
linked resources.

But even in the latest Eclipse Platform release (Galileo,) the
Eclipse project file management is still problematic when it comes
to working with files located outside of the project directory.

The main limitations are the following:

Virtual project file structure

The existing resource primitives in Eclipse do not fully allow
the user to create truly arbitrarily complex file structures in
projects. The limitation is that in order to create a given
hierarchy, the only container objects available are the folders and
linked resource folders. Unfortunately, both require an actual
folder located on the file system; the only difference between them
is whether their parent in the workspace tree is the same as their
parent in the file system.

 To alleviate this limitation, e4 now supports Groups. A
group is a container (seen by the API as a normal IFolder resource)
that has no location in the file system. Because of this, only
linked resource files and folders can be created under a group.

Groups appear in resource navigators as purple folders, to
distinguish them from regular folders.

The project explorer has been made group-aware, so that normal
drag and drop operations in the project explorer where the target
is a group are handled in the most appropriate way. For example,
when the user drag and drops a normal file resource on a group,
instead of simply giving an error, a linked resource pointing to
the original file is automatically created.


The first requirement when recording a list of files in a
project, is that the file’s location has to be recorded in a way
that is portable across computers.

Until Galileo, the mechanism to record linked resources relied
on a workspace level list of variables, and the user specified the
relative linked resource location. Because this variable list was
maintained in the workspace .metadata folder, along with a myriad
of user settings, using linked resources in a project practically
made the project non-portable across computers and even across
workspaces on the same computer.

In e4, projects now store their own path variable list in the
.project file. A new property page, available in the project
Properties, allows the user to see and edit the path variables.
Default path variables are available for all projects, including
PROJECT_LOC, which is automatically initialized to the project
directory location.

Third party plugins can also extend the default project path
variable list through the variableProviders core.resources
extension point.

Ease of use

One of the main obstacles to the use of linked resources in
Eclipse is the tedious process of creating linked resources, which
require the user to go through the new file/folder wizard, and
create linked resources one by one; specifying the location each

In e4, the user is now able to create linked resources simply by
dragging and dropping from the OS shell (i.e. Windows Explorer)
into the workbench project explorer. A dialog then appears, letting
the user choose which type of resource should be created.

The first choice consists of the legacy Eclipse behavior:
copying all the files under the target location. The second choice
allows the user to automatically create a hierarchy of groups and
linked resources files, mimicking the file system hierarchy.

The third will generate only linked resources for each file and
folder contained in the drag source, without creating any

When linked resources are created, the user can allow Eclipse to
automatically generate the location as relative to the most
appropriate variable (typically PROJECT_LOC), or explicitly select
the variable where the linked resources locations should be


Many changes have been implemented to make linked resources a
first class workflow in Eclipse. One of those changes is allowing
the user to change the location of a linked resource from the
resource property page.

Another improvement is the ‘Linked Resource’ editor in the
project property page, where the user can view all the project’s
linked resources in one convenient location, grouped by their
location error status. Here, the linked resource location can be
converted automatically, variables created, and locations


Another new feature in e4 is the resource filters.

Resource filters allow the user to configure which file system
resources will be visible to the Eclipse workspace tree when a
refreshLocal() is performed. The user can create include-only
filters, exclude-all filters, and specify if these apply to files,
folders, or both. They can also be set to be inheritable, so all
children of a given container will inherit the filters

The filters run at the lowest level of the core.resource API, so
that resources can exist in file system hierarchies containing tens
of thousands of files without taxing the core.resource plugin with
a penalizing memory and performance overhead.

Only normal file and folder resources that are implicitly
populated in the workspace tree by the refresh mechanism are
subject to the resource filters. Because the user explicitly
creates linked resources and groups, the resource filters do not
apply to them.

Resource filters can be specified on a group resource, but they
will be effective only as far as they are set to be inheritable,
and apply only to the group’s children that are linked in the
resource folder.

Resource filters can also be specified on a container before the
container is created (either in the new resource wizard, or
programmatically), so that the initial refresh() will be filtered

New filter types can also be added through the filtersProviders
core.resources extension point.

Backward Compatibility

All the new e4 features are fully compatible with the existing
Eclipse 3.x API contracts. All plugins that use the existing
core.resources APIs will transparently work in workspaces and
projects that are using the new e4 features, including groups,
project path variables and resource filters.

The only subtle difference, is that groups are seen by the
plugins as linked resource folders that always return null when
IResource.getLocation() and IResource.getLocationURI() are

Since this was already a valid return value for those APIs, if a
3.x plugin already handled this properly, it will work
transparently in e4.

Future Improvements

Many improvements are still being discussed in the
core.resources, including automatic project provisioning, project
reference overhaul using linked resources, performance improvements
when serializing the .project file, etc…

Using the new Linked Resources APIs

One can imagine that, if the e4 core.resources features were
made available in Eclipse 1.0, many IDE features would have been
implemented differently.

For example, the JDT Java Build Path/Libraries feature
duplicates many of the basic linked resource features to locate
.jar files, and this would have conceivably been implemented

Similarly, e4’s comprehensive and flexible set of APIs for
managing project resources widens the domains where the
core.resource API can successfully be used.

Serge Beauchamp
Serge Beauchamp is Senior Software Engineer at Freescale Semiconductor, formerly the semiconductor division of Motorola. He has been developing C/C++ IDE since 2000 where he joined the IDE team at Metrowerks to work on their CodeWarrior tools. He is an Eclipse Platform committer and has been involved in the E4 Resource improvement effort.
comments powered by Disqus