This GEF Adopter Guide provides all necessary information to enable adopters (see definitions of three different communities) to develop against GEF. Contributors and committers, who want to contribute to GEF, should rather consult the GEF Contributor Guide.
- 1 Preparing your development environment
- 1.1 Install Java 7 and/or Java 8 JDK
- 1.2 Download and Start Eclipse IDE
- 1.3 Specify Execution Environment for JavaSE-1.7 and/or JavaSE-1.8
- 1.4 Define and Set Target Platform
- 1.5 Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)
- 2 Starting an (Eclipse Application) runtime, resolving JavaFX runtime dependencies
Preparing your development environment
Install Java 7 and/or Java 8 JDK
If you want to develop against GEF 3.x, any current Java JDK may be used (the code base is backwards compatible to J2SE-1.4). If you want to develop against GEF4 (and use JavaFX in your client code), you will need to have at least a Java 8 JDK installed (GEF4 is compatible to the JavaSE-1.7 but the e(fx)clipse PDE integration, which is needed to resolve JavaFX dependencies, requires a Java 8 JDK to work properly). If your own code is intended to be compliant to Java 7, you should in addition have a Java 7 JDK that includes Java FX 2.2 (Oracle JVM > 1.7.0_45) installed.
Download and Start Eclipse IDE
In order to develop against GEF 3.x or GEF4 we recommend to download an 'Eclipse IDE for Eclipse Committers' from Mars and to prepare it as outlined in the following sections.
If you want to develop against GEF4 and have JavaFX dependencies in your client code, the e(fx)clipse JavaFX-PDE-integration tooling that is needed to resolve JavaFX dependencies (see Install e(fx)clipse JavaFX-PDE-integration), requires that you start your eclipse IDE with a Java 8 JVM.
If Java 8 is not your system default, follow the instructions given in Specifying the JVM to specify that a Java 8 JVM is used for starting your IDE. Please note that the Java JVM that is used for starting the IDE is unrelated to your actual development target, which might still refer to BREE JavaSE-1.7 and JavaFX 2.2. It is only needed for the e(fx)clipse JavaFX-PDE-integration tooling to work properly.
Install e(fx)clipse JavaFX-PDE-integration
When developing bundles that depend on JavaFX, it is required to install the e(fx)clipse JavaFX-PDE-integration (
org.eclipse.fx.ide.pde.feature) into your Eclipse development environment to properly resolve JavaFX dependencies within your workspace. This is needed because JavaFX is not included on any of the default OSGi classpaths, so JavaFX dependencies in your bundles will otherwise not be properly resolved (unless you manually add the respective jars to your classpath, which is not recommended). The e(fx)clipse JavaFX-PDE-integration will automatically add additional classpath entries for those bundles that contain classes with javafx.* imports. It requires that a JVM, which provides JavaFX, is registered as an installed JRE and is used to resolve the execution environment matching that of the respective bundle (as outlined above).
Please install e(fx)clipse - IDE - PDE (
org.eclipse.fx.ide.pde.feature.feature.group) in a version matching your development environment. For Mars, it can be installed in version 2.0.0 from http://download.eclipse.org/releases/mars (uncategorized) or the e(fx)clipse 2.0.0 release site (e(fx)clipse - single components category).
Please note that from Mars M7 onwards (or more precisely beginning with gef4-master build #2316, 2015-04-25), development against GEF4 will require e(fx)clipse in at least version 2.0.0 and will not work with earlier versions of e(fx)clipse. This is because GEF4 bundles no longer specify javafx.* package imports, and JavaFX dependencies will thus not be resolved with earlier e(fx)clipse versions. Please note that e(fx)clipse 2.0.0 can also be used in a Luna development environment.
Specify Execution Environment for JavaSE-1.7 and/or JavaSE-1.8
In order to have the JavaFX dependencies of bundles with BREE JavaSE-1.7 (JavaFX 2.2) and JavaSE-1.8 (JavaFX 8) resolve properly by the e(fx)clipse JavaFX-PDE-integration, the Java execution environments for JavaSE-1.7 and JavaSE-1.8 have to be properly resolved against matching Java JVMs. Note that it is required to properly resolve JavaSE-1.7 to a matching Java 7 JVM even if you want to use a Java 8 JVM for launching a runtime or for later deployment.
In case you have bundles with JavaFX dependencies and JavaSE-1.7 BREE, you will thus have to ensure that a Java 7 JVM, which provides JavaFX 2.2 (e.g. an Oracle JVM), is used to resolve the JavaSE-1.7 execution environment in your IDE. The e(fx)clipse JavaFX-PDE integration will only be able to resolve all JavaFX dependencies (of a bundle with JavaSE-1.7 BREE), if the respective
jfxrt.jar (which bundles the JavaFX 2.2 classes) can be located in the installation location of the JVM, against which the JavaSE-1.7 execution environment is resolved. In order to ensure that this is the case, go to "Windows -> Preferences -> Java -> Installed JREs" and ensure a compatible Java SE 7, which provides JavaFX 2.2, is installed.
Eclipse will automatically detect the jar libraries provided by the JVM and add it to the registration. Note that the
jfxrt.jar will actually not be added to the JVM definition, and that it does not have to be manually added to it either, because the contained JavaFX classes will be added to the classpath of all bundles with javafx.* package imports (and JavaSE-1.7 BREE) by the e(fx)clipse JavaFX-PDE-integration automatically. To ensure that the respective JVM is used to resolve the JavaSE-1.7 execution environment, go to "Windows -> Preferences -> Java -> Installed JREs -> Execution Environments" and select it there.
In case you have bundles with JavaFX dependencies and JavaSE-1.8 BREE, you will have to ensure that a compatible Java 8 JVM, which bundles JavaFX 8.0, is registered as installed JRE and specified to resolve the JavaSE-1.8 execution environment. Note that here, the
jfxrt.jar will be automatically added to the JRE definition when registering the Java 8 JVM. However, the
jfxswt.jar will not be added (it contains the javax.embed.swt.* classes), and it also does not have to be manually added to the JVM definition as well, as it will be added to the classpath of all bundles that have JavaFX dependencies (and JavaSE-1.8 BREE) by the e(fx)clipse JavaFX-PDE-integration.
Define and Set Target Platform
In order to control against which version of GEF 3.x or GEF4 you develop, you should set up a target definition file. To do so, go to "File -> New -> Other..", then choose "Plug-in Development -> Target Definition". Your target definition will have to include the respective GEF 3.x or GEF4 components from one of our update-sites (it is recommended to use the SDKs as these contain sources), as well as their respective dependencies. This might be achieved easiest if you transfer these dependencies from one of the target files provided by
org.eclipse.gef4.target). If you want to develop against GEF4 and/or your bundles contain JavaFX dependencies, it is important that your target bundles the
org.eclipse.fx.runtime.min.feature, which will be needed to resolve JavaFX dependencies at runtime (i.e. when starting a runtime Eclipse Application).
Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)
As all GEF4 API is currently released as provisional, all GEF4 API package exports are guarded with the x-internal directive (see Marking stable, provisional, and non-API for details).
Dependent on your workspace settings, this may lead to a lot of Java compiler warnings/errors in your client code, which result from discouraged API access. You may want to adjust your workspace-wide Java and Plug-in compiler preferences to get rid of them.
- Go to "Preferences -> Java -> Compiler -> Warnings/Errors", then select the respective severity ("Warning", "Ignore") for the "Deprecated and restricted API -> Discouraged reference (access rule)" entry.
- Go to "Preferences -> Plug-in Development -> Compilers", then select the respective severity ("Warning", "Ignore") for the "References ->References to discouraged classes" entry.
Starting an (Eclipse Application) runtime, resolving JavaFX runtime dependencies
When launching an Eclipse runtime that contains bundles with JavaFX dependencies, the e(fx)clipse
org.eclipse.fx.osgi fragment have to be included in the runtime configuration.
-Dosgi.framework.extensions=org.eclipse.fx.osgi has to be added to the VM arguments in the runtime configuration's Arguments tab. If you are having problems with the e(fx)clipse runtime resolution you can add
-Defxclipse.osgi.hook.debug=true to the VM arguments to enable debugging output.
We noticed that JavaFX does not seem to work correctly when running SWT on GTK 3. In this case, you can enforce SWT to use GTK 2 by setting the environment variable
SWT_GTK3=0 or adding
--launcher.GTK_version 2 to your eclipse.ini.