E4/Compatibility/Running the compatibility layer

This is now a historical document. The Workbench (compatibility) layer has been included in eclipse since Juno

Current (4.0 M6 and later)

There are no longer any steps required to run the compatibility layer. It is now fully integrated into the Eclipse SDK 4.0 builds. Just download the latest build, and start it up like you would with any version of eclipse. See E4/Self Hosting for the current list of issues we're working on in the 4.0 Builds.

To develop or change the model in the latest builds, you need to have EMF SDK installed, plus some of the source bundles. You can also use the Advanced Workbench Model Editor from the e4 Tools.

• EMF SDK - org.eclipse.emf.sdk
• Eclipse e4 Modeled Workbench - org.eclipse.e4.ui.feature - to develop you need the source feature as well
• Eclipse e4 CSS support - org.eclipse.e4.ui.css.feature - to develop you need the source feature as well
• Eclipse e4 Tools - org.eclipse.e4.core.tools.feature

I use the director to install the tools I need in 4.0:

eclipse/eclipse -application org.eclipse.equinox.p2.director \
-consoleLog -noSplash \
-repository http://download.eclipse.org/eclipse/updates/4.0,\
http://download.eclipse.org/e4/updates/2010,\
http://download.eclipse.org/releases/helios \
-installIU org.eclipse.releng.tools.feature.group,\
org.eclipse.emf.sdk.feature.group,\
org.eclipse.e4.ui.css.source.feature.feature.group,\
org.eclipse.e4.ui.source.feature.feature.group,\
org.eclipse.e4.ui.css.feature.feature.group,\
org.eclipse.e4.ui.feature.feature.group,\
org.eclipse.e4.core.tools.feature.feature.group

1.0M4 - Legacy Information

A screenshot showing the current state of the e4 Eclipse 3.x compatibility layer as of 1.0M4.

This section describes how to run the e4 compatibility layer.

Setup

1. Download a recent e4 SDK here.
2. Add this CVS repository location to your workspace setup: :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse
3. Checkout the org.eclipse.e4.ui.releng module from the /cvsroot/eclipse's e4/releng directory.
4. Right-click on the e4.ui.compatibility.psf file and select 'Import project set...'. When you are prompted for a password, just enter anonymous as your user name and leave the password as blank.
5. If a project loaded by this *.psf file has a compilation error, right click on the project and select 'Replace with > Another Branch or Version...'. In the resulting dialog, click 'Refresh Tags', select 'Versions > R1_0M4', and click 'OK' to load the 1.0M4 code.

Running the compatibility layer

1. Open the e4-legacy-ide.product file in the org.eclipse.e4.ide.application project.
2. Click on the 'Launch an Eclipse application' button in the 'Overview' tab to generate a launch configuration. An error will occur.
3. Open the generated launch configuration and go to the 'Plug-ins' tab.
4. In the 'Launch with:' combo control, select 'all workspace and enabled target plug-ins'. Now click 'Run' to launch the compatibility layer.

0.9

A screenshot showing the current state of the Eclipse 3.x compatibility layer.

This demo shows the current state of the eclipse 3.x compatibility layer . The image shows a workbench populated from an IPerspectiveFactory. The resulting menu, stacks, views and Editor Area are creating by turning the API calls into changes to the modeled UI's structure.

The views and editors are created through the LegacyViewFactory, a specialized PartFactory that mimics the part creation protocol (creating the executable extension for the part, calling 'createPartControl'...) in eclipse 3.x.

Setup

Warning: These setup instructions are significantly different from the various e4 demos because of technical constraints on fragment development.

Unlike the demos, we have to sacrifice (possibly) some stability because the current fragment handling code requires that the workspace contains a checked out org.eclipse.ui.workbench project. If the base eclipse that you are running is not recent then the workbench project may fail to compile due to underlying project changes and you could end up 'pulling on a piece of thread' (i.e. checking out multiple other projects one after the other to satisfy the compilation requirements).

Install Eclipse

Start with a fresh install of the latest I-build.

Install EMF

1. "Help" -> "Install New Software..."
2. Select the "http://download.eclipse.org/releases/galileo" update site
3. Open "Models and Model Development"
4. Check "EMF SDK - Eclipse Modeling Framework SDK"
5. Hit "Next" as necessary (accepting the license agreement)
6. Hit "Finish"
7. Restart eclipse when prompted

Load the compatibility layer

1. Open the CVS Repositories view
2. Add a new connection to dev.eclipse.org with the repository path 'cvsroot/eclipse', if you are not a committer simply use 'anonymous' as the User name.
3. Check out the 'e4\releng' project from HEAD

Import these project sets.

Now you should have a 'releng' project in your workspace. Drill down into 'org.eclipse.e4.ui.releng', select both 'e4.ui.psf' and 'e4.ui.compatibility.psf', right-click and select 'Import Project Set...'. This will check out the projects that you need in order to run the compatibility layer.

Running the Code

1. Open /org.eclipse.e4.ui.examples.legacy.workbench/legacy-eclipse.product. This gets you a PDE product editor.
2. Click on the "Launch an Eclipse Application" link.

Click here to run the compatibity demo.

You should see a Shell similar to the one depicted above.

The first time you run the workspace will be empty, the following gestures will work to populate it with projects...

• New -> Project.. : You can access this through the Project Explorer's context menu (the main menu version is empty at the moment)
• CVS : You can create a CVS connection (as you had to do to install the compatibility layer into your outer eclipse workspace) and check out projects.

Now that you have something to work with you can 'kick the tires'. Many of the standard UI gestures (double-click to open, Ctrl-S to save) work but you may experience some that don't. The save will trigger the compiler/builder as necessary and update the problem view... Also, the '>' adornment will appear if the file is shared in CVS.

The current code is capable of performing a complete modification cycle; check out, make changes, save (w/ compile/update) and check in. We're currently working on getting the Debug part of the development workflow working; creating/launching a debug session, adding breakpoints, getting the Breakpoints and Variables views up...so far we have the Debug View working, you can add breakpoints (using the context menu in the editor) and they'll trigger when hit. In order to launch an 'inner' Debug session you should right-click in the Project Explorer and use the "Debug As >" menu.

NOTE: This is still a work in progress, many things work and many don't. To fill the gaps we'll try to give known 'working' UI gestures to accomplish various activities.

Caveats:

• Right now we don't support parameterized commands, meaning that some very useful menu functionality is missing (notably "Import..." and "Show View..."), they're coming!.
• In general you're better off using the various view's context menus rather than the main menu equivalents.
• There is only one perspective so saying 'yes' to prompts to switch perspectives won't get you there
• When editing you'll notice some oddities;
  • 'Delete' doesn't work but 'Backspace' will ('Delete' is a parameterized command)
  • The Copy/Paste key bindings don't work but the context menu does

Adding CSS Styling

OK, it's...um...functional (sort of) and this is e4, we've gotta be able to do better than that...

Close the e4 session if it's open Return to the 'releng' project and import e4.ui.css.psf

Re-run your e4 session, it should now be styled. The path to the CSS file can be found in /org.eclipse.e4.ui.examples.legacy.workbench/plugin.xml

<property
    name="applicationCSS"
    value="platform:/plugin/org.eclipse.e4.ui.examples.legacy.workbench/css/xp-silver-legacy.css">
</property>

Edit the file and kick the tires (it's fun...;-) ! You'll have to restart your e4 session to pick up the changes.

Under the Covers

The bulk of the compatibility layer's implementation resides in the /org.eclipse.e4.ui.workbench.fragment project. A 'fragment' is a special type of OSGI bundle that has the ability to provide a relpacement for classes defined in some other bundle (in this case org.eclipse.ui.workbench).

What do we have and how is it done? Providing the ability to host 3.x components in the e4 workbench is a mix of three different approaches...

• Replace: We need to replace some of the top-level classes such as:
  • PlatformUI : the root singleton through which the rest of the UI functionality is accessed.
  • Workbench : The main class for a running eclipse session.
  • WorkbenchWindow : The main implementation class for an eclipse window
  • WorkbenchPage : Essentially more implementation for a WorkbenchWindow

We expect that over time we will also have to replace some of the (possibly abstract) base classes used in the API such as ViewPart and EditorPart in order to have them integrate correctly into the e4 environment.

• Re-use: Many of the capabilities available through the Workbench[Window[View|Editor]]] are implemented as discreet classes that encapsulate their functionality. Where appropriate we simply instantiate the 3.x class. In some cases (i.e. providing selections, Command infrastructure) we will be forced to re-implement the functionality in order to merge it into the e4 architecture correctly).

• Re-implement: Where the API returns an interface and where the existing implementation (if any) is not suitable for use in e4. the layer will re-implement the interface itself, mapping the various method's functionality into the e4 structure.