Installation requirements for embedded browsers on Linux systems

Technote (troubleshooting)

Problem(Abstract)

When attempting to open the workbench in IBM Rational Application Developer (*), it either closes immediately after starting, or does not start at all.

On Linux systems, the Eclipse Standard Widget Toolkit (SWT) might not be able to find and use the default native browser. Additional steps might be required to configure the browser setup before the product works correctly.

This note summarizes information that is contained in various locations within the SWT FAQ document.

Symptom

One of the most common symptom about this problem is an Eclipse window displays the following message: JVM terminated. Exit code=160.

After you close the Eclipse message window, a javacore file (for example, javacore.20140715.102137.20388.0002.txt) is created in the installation directory.

Other symptoms can be product features that use an embedded web browser might not work correctly. Problems can include possible failure scenarios, showing an error message, or simply not showing the expected output. The product features that use an embedded browser include:

Rich Page Editor

Web Browser component (Open With->Web Browser)

Welcome page

Page Designer Preview pane

Cause

The product features that use an embedded browser use Eclipse SWT to create the browser widget. In addition to installing the latest version of the browser product, SWT has specific installation requirements for the Mozilla and WebKit browser types. Eclipse SWT is only compatible with a range of XULRunner library versions that are installed with Firefox.

Rational Application Developer 7.5.x (*) is based on Eclipse 3.4.x and is compatible with:

Environment

Diagnosing the problem

If IBM Rational Application Developer (*) crashes or doesn't even start and end with an error message containing JVM terminated. Exit code=160

Use Rich Page Editor to open a web page. Rich Page Editor is the default editor for HTML page types.

if the embedded browser code is not properly installed or the product is not properly configured, then an error message is typically displayed in the Design view. Process failures might result from version conflicts with some unsupported levels of Mozilla's XULRunner package.

Resolving the problem

Eclipse SWT supports the following browser types for Linux systems:

Mozilla (Firefox) through the XULRunner package

WebKit through WebKitGTK+ shared libraries

Although the version of Eclipse included in the product determines the default browser type, you can also explicitly configure the default browser type. Only one browser type is available at a time within the product.

XULRunner requirements: The XULRunner package enables Mozilla as an embedded browser. If several XULRunners are installed on the same system, version mismatches might occur even when a specific XULRunner installation is registered as the default version. To clearly define the configuration, set up an explicit pointer to a XULRunner version:

In the eclipse.ini file that is included in the product installation, locate the -vmargs section. Note that some IBM Worklight Studio installations use JRE arguments from the Worklight.sh script instead of from the eclipse.ini file. If a Worklight.sh file is present in the same product directory as the eclipse.ini file, add your updates to the -vmargs sections of both files.

In the -vmargs section, add a JVM system variable:

-Dorg.eclipse.swt.browser.XULRunnerPath=/home/myuser/xulrunner

where /home/myuser/xulrunner is the path to the root of an uncompressed XULRunner package.

If you are using Eclipse version 3.6.x: Mozilla is the default browser type used by SWT on Linux. The supported versions of XULRunner are 1.8.x - 1.9.2.x and 3.6.x. The XULRunner 1.9.2.x packages are preferred (these are equivalent to Firefox version 3.6.x); links to suitable downloads are included in the related information section of this note. The XULRunner package must match the architecture (32-bit or 64-bit) of the product installation.

Note: Newer XULRunner or Firefox installations do not work as an embedded browser. Attempting to use higher versions might result in product failures when attempting to initialize the native browser code.

If you are using Eclipse versions 3.7 and later: If the WebKit browser type is available, SWT uses this browser type by default. If WebKit libraries are not found, SWT attempts to locate a suitable XULRunner installation and create an embedded Mozilla browser. The requirements for XULRunner versions are the same as those specified for Eclipse version 3.6.x.

To force SWT to use XULRunner instead of WebKit on these higher versions of Eclipse, add the following JVM parameter to the -vmargs section at the end of the eclipse.ini file (and Worklight.sh, if present):

-Dorg.eclipse.swt.browser.DefaultType=mozilla

NOTE: These two vmargs must be used together:

-Dorg.eclipse.swt.browser.DefaultType=mozilla

-Dorg.eclipse.swt.browser.XULRunnerPath=/home/myuser/xulrunner
, where /home/myuser/xulrunner is the path to the root of an uncompresse

Both must be present if using Mozilla/FireFox

WebKit requirements: A WebKit embedded browser is supplied by a separate installation of the WebKitGTK+ shared libraries. These libraries might already be included for many supported Linux distributions.

If you are using Eclipse version 3.6.x: Only version 1.2.x of WebKitGTK+ is supported. If later versions of the WebKit shared libraries are present and you want to use WebKit in this configuration, you must remove and replace them with version 1.2.

To force SWT to use WebKit, add the following JVM system parameter to the -vmargs section at the end of the eclipse.ini file (and Worklight.sh, if present):

-Dorg.eclipse.swt.browser.DefaultType=webkit

If you are using Eclipse versions 3.7 and later: These versions of Eclipse support any WebKitGTK+ libraries of 1.2.x or later. Since WebKit is the default browser type, the shared libraries are automatically used if SWT can find them. If suitable libraries are not found, SWT attempts to use XULRunner instead.