This guide provides all necessary information to enable contributors and committers to contribute to the Eclipse Graphical Editing Framework (GEF) project. Users, who want to use the end-user tools, as well as adopters, who want to develop applications against GEF, should rather consult our README.
You can set up a pre-configured IDE for the development of GEF FX using the following link:
This automates all the steps below, many of which are outdated.
The current 5.4 (2022-06) development stream uses a minimal BREE (bundle required execution enviroment) of JavaSE-1.8 for all bundles. However, GEF aims to be compatible to Java 11, so if you want to contribute, you will thus have to install a current Java SE Development Kit 11. In addition, you will need a matching version of JavaFX.
We recommend to download a recent 'Eclipse IDE for Eclipse Committers (2022-03)' package and to prepare it as outlined below.
-
Install
PDE API Tools Execution Environment Descriptors -
Install
e(fx)clipse - IDE - PDEfrom https://download.eclipse.org/efxclipse/updates-released/3.8.0/site/ -
Install
Xtext Complete SDKin version 2.26 -
Install
m2e - Maven Integration for Eclipse (includes Incubating components)
See below for details.
All production code bundles (i.e. excluding doc and test bundles) are configured to have PDE API tooling enabled. The API checks, which are configured on a project-specific basis, include checks for references that do not exist in the specified execution environment. As API tooling requires execution environment descriptions (see Installing Execution Environment Descriptions for details) to perform the respective checks, these need to be made available, because otherwise you will see warnings for missing execution environment descriptions.
In order to properly resolve all JavaFX dependencies, the JavaFX-PDE-integration (org.eclipse.fx.ide.pde.feature) provided by the e(fx)clipse project is required. As certain parts of JavaFX (e.g. the SWT integration) are not included in the JRE definition, the respective classes will not be available as a JRE System Library to the GEF bundles. The e(fx)clipse JavaFX-PDE-integration will automatically add additional classpath entries to the bundles, so all these dependencies can also be resolved.
Install e(fx)clipse - IDE - PDE (org.eclipse.fx.ide.pde.feature.feature.group) in a version matching your IDE. For 2022-03, it can be installed in version 3.8.0 from https://download.eclipse.org/efxclipse/updates-released/3.8.0/site/.
To ensure that the e(fx)clipse JavaFX-PDE integration can properly locate those JavaFX libraries that are not included in the JRE definition, the Java execution environment for JavaSE-1.8 has to be resolved against a matching Java 11 JDK. To ensure that this is the case:
- Go to Windows -> Preferences -> Java/Installed JREs and ensure the installed Java SE Development Kit 11 is listed (otherwise add it manually).
- Go to Windows -> Preferences -> Java/Installed JREs/Execution Environments and make sure JavaSE-1.8 is mapped to the installed Java SE Development Kit 11 (the checkbox needs to be checked, otherwise e(fx)clipse will not be able to resolve the JavaFX dependencies).
- Go to Windows -> Preferences -> JavaFX and configure JavaFX 11 + SDK to point to the
libfolder of your OpenJFX installation.
Parts of the DOT bundles (org.eclipse.gef.dot, org.eclipse.gef.dot.ui) contain sources that are generated by Xtext as well as Xtend. These generated sources are not contained in the Git repository and have to be generated locally within the development workspace. The Xtend files will be automatically compiled to Java files (by means of a builder) as soon as the Xtend IDE is installed. The generation of Xtext artfifacts however needs to be triggering manually (see [Generate Xtext Artifacts](#Generate Xtext Artifacts)), which requires installation of Xtext Complete SDK into your Eclipse IDE, or by executing a local Maven build (see below).
In case you want to run a headless build locally in your workspace, the Maven Integration (m2e) is needed, as the headless build is based on Maven/Tycho.
Please install m2e - Maven Integration for Eclipse (includes Incubating components) in a version matching your IDE. (It is already pre-installed in the IDE for Eclipse Committers mentioned above.)
To ensure that bundle versions and Maven pom.xml versions are in sync, the Eclipse RelEng Tools are very helpful.
It is recommended that you install the 'Eclipse RelEng Tools' into your IDE. Please make sure that you install it in a version matching to your IDE. For Neon, it can be installed in version 3.9.0 from http://download.eclipse.org/eclipse/updates/4.6.
Having set up the Eclipse IDE, next is to fork the repository and to check out the sources into the local workspace. Using EGit, this can be performed as follows:
- Copy the URI of your repository fork to your clipboard.
- Open the Git perspective (provided by EGit) within Eclipse, and click on Clone a Git repository.
- Select Clone URI and press Next >.
- If you have copied the URL of your fork into the clipboard before, the upcoming Clone Git Repository dialog should already provide the necessary entries for URI, Host, and Repository path, so you may simple forward by pressing Next >.
- Select the branches you want to clone from remote. The master branch is the one used for the current development stream. Development in maintenance releases is performed in respective maintenance branches. After having selected all branches of interest, press Next > to continue.
- Choose a local directory to store the cloned repository (the default will be located under your home directory), select the Initial branch to check out, and check the box to Import all existing Eclipse projects after clone finishes. Press Finish.
- Switch back to the Java perspective.
Multiple target definition files are provided by the org.eclipse.gef.target project. To specify the target platform, simply open the respective target definition (e.g. 2022-03.target) within the Target Editor, let it fully resolve (i.e. wait until the Resolving Target Definition background task has finished and the installable units are listed under the respective Locations), then choose to Set as Target Platform).
In case the target editor does not properly resolve the target definition, an invalid target cache may be the cause. In such cases, opening the target definition file with a text editor and incrementing the sequence number manually, will invalidate the cache when reopening it with the target editor again. After the cache has been invalidated, the sequence number can be restored.
All production code bundles (i.e. excluding doc and test bundles) are configured to have PDE API tooling enabled. It is used to ensure compliance of sources to the specified execution environments, as well as to ensure proper semantic versioning. As PDE API tooling requires the definition of an API baseline you will see errors after having checked out the code ('An API baseline has not been set for the current workspace.').
API-baselines are provided by the org.eclipse.gef.baseline project. You may define them by going to Preferences -> Plug-in Development -> API Baselines, then choose to select "Add Baseline..." and point to the plugins sub-folder of an API baseline located in the baselines project (note that the dialog browses the file system instead of the workspace, so you will have to point into the respective folder in your local Git repository).
Parts of the DOT code base (org.eclipse.gef.dot, org.eclipse.gef.dot.ui) contain sources that are generated by Xtext. These generated sources are not contained in the Git repository and have to be generated locally within the development workspace.
If you have installed Xtext in your IDE, you can manually trigger the Xtext artifact generation by selecting Dot.xtext within the org.eclipse.gef.dot.internal.language package in org.eclipse.gef.dot in the Package Explorer, and by choosing Run As -> Generate Xtext Artifacts from the context menu.
Alternatively you may execute a Maven build locally. Make sure to refresh the org.eclipse.gef.dot and org.eclipse.gef.dot.ui projects in your workspace after having executed the local build (Refresh from context menu on respective projects, or F5), and make sure to clean your workspace afterwards (Project -> Clean -> Clean all projects).
Having properly set up your development environment you can start working on the necessary changes. Please ensure to execute the all test-suite that exists for each bundle that was changed to be safe against regressions. In case your change is not trivial, it is recommended to add respective tests to demonstrate that the fix is adequate. You can either call the AllTests suite contained in the test bundles of all GEF components, or run a headless Maven build locally (which will also execute the tests).
GEF uses a Maven/Tycho-based build infrastructure. With the Eclipse Maven Integration, a headless build can also be executed in the local workspace. Make sure you have checked out all projects of the respective git repository. Then easily run the build by right-clicking the pom.xml file located within the org.eclipse.gef.releng project, and selecting 'Run As -> Maven build...'.
In the configuration wizard you have to specify the goals ("clean verify") and the target profile (e.g. "2022-03.target") for the build. Note that without setting the target profile the build will not run successfully. The build needs to be executed with a Java 11 VM, so if you have installed multiple JVMs, you should check the settings in the JRE tab.
As a result of the build, an update-site will be created in the target sub-folder of the org.eclipse.gef.repository project.
This Eclipse Foundation open project is governed by the Eclipse Foundation Development Process and operates under the terms of the Eclipse IP Policy.
- https://eclipse.org/projects/dev_process
- https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf
In order to be able to contribute to Eclipse Foundation projects you must electronically sign the Eclipse Contributor Agreement (ECA).
The ECA provides the Eclipse Foundation with a permanent record that you agree that each of your contributions will comply with the commitments documented in the Developer Certificate of Origin (DCO). Having an ECA on file associated with the email address matching the "Author" field of your contribution's Git commits fulfills the DCO's requirement that you sign-off on your contributions.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Your changes should be comprised to a single commit (squash if necessary) and the commit needs to be properly signed off to mark its CLA-compliance.
The commit message should follow the following structure:
'['(<bug-id>|'NONE')']' <one-line-summary-or-single-line-commit-message>
(<wrapped-detailed-commit-message>)?
Signed-off-by: <author-name> '<'<author-email>'>'
Bug: <url-of-bugzilla-issue>
Example:
[493136]: Create DotSampleGraphs.xtend with sample graph definitions.
- Extract the definitions of the sample dot graphs into a separate DotSampleGraphs.xtend file (utilize the xtend multi-line string functionality).
- Reuse these sample graph definitions within the DotParser and DotInterpreter test cases.
- Modify the org.eclipse.gef.dot.tests plugin to be able to handle the Xtend generated files (.classpath, .gitignore, .project, build.properties, pom.xml).
- Implement additional DotParser test cases.
Signed-off-by: Tamas Miklossy <miklossy@itemis.de>
Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=493136
If your contribution does not exceed the contribution limit (currently 1000 LOC) this will allow us to directly accept your pull request. If your contribution was not developed from scratch or contains content from other authors, please indicate this on the related Bugzilla entry. As in cases where the contribution exceeds the limit, we will have to open a contribution questionnaire (and may have to ask for additional information via the related Bugzilla) to handle such cases in compliance to the Eclipse Legal Process.