How to create a cross-platform Java OpenGL Eclipse Plugin ready to use in your development environment and installed from a repository via the Eclipse update/install software functionality.
This project is inspired by the work of Wade Walker and the information available on his blog. The first steps of the tutorial A cross-platform graphical application using Java, OpenGL and Eclipse detail how to pack JOGL Java binding to OpenGL files provided by JogAmp into Eclipse plugins.
Building a cross-platform Eclipse plugin is easy following the information available. Not so straightforward is the process of making the plugin deliverable. The following choices are available
- Plugin Development Environment (PDE) UI
- PDE headless
- Maven + Tycho
Using PDE to manually generate a p2 repository for an Eclipse feature project is the obvious starting point, but in the case of multiple environments to be supported this won’t work. The PDE UI will generate all the plugins but the fragment for the first set of <os>+<window>+<arch> only. The option of a PDE headless build has not been tested. Last listed is the option discussed hereafter, which proved to be successful.
An automated build with Maven and Tycho produces the expected results. However, the learning curve is steeper compared to a manual build if one is not familiar with the tools yet.
Support for Maven is added to Eclipse installing the m2e plugin (installation steps). No further installation of Maven itself is required as an embedded version resides within m2e. Tycho is a Maven 3 extension (already included) that enables the automation of tasks specific to plugin development.
Once complete and ready for build the projects in the workspace will have a configuration similar to the Tycho Multiplatform Reactor Tutorial (this is referred in the following simply as “Tycho tutorial”).
The following list of components is available in the Eclipse workspace (see Wade Walker’s tutorial). The JOGL version used here is 2.3.0
- a JOGL main plugin project (contains high-level Java OpenGL )
- fragments (contain native JOGL libraries)
- a feature project containing the former components
- a JOGL tests plugin project (contains JOGL-enabled Eclipse ViewPart)
- a feature project containing the test plugin
- a site project listing both features
Add maven support
Each plugin is promoted to a Maven project with right-click on the project folder and selecting Configure > Convert to Maven Project. Provide the following details in the Create new POM dialog
- Artifact ID equal to the plugin name
- clear the Group ID
- clear the Version
- Packaging: eclipse-plugin (if project is plugin/fragment), eclipse-feature (if project is feature), eclipse-update-site (if project is the update site) typing it manually as they’re not available from the dropdown
Upon successful creation the new pom.xml is still not complete and contains errors. Bear with it for the moment, the errors/warning will be fixed when the next section is complete. Open the pom.xml of a fragment plugin and add the following code to the <project></project> section changing the <os> <ws> <arch> to be the ones relevant for the fragment
NOTE: The POM editor featured advanced tabs with a specific plugin UI that would allow for the previous modification to be possible without editing the raw content. These tabs are not available in editor 1.0+ (see the related post and an overview of the old editor
The update site plugin doesn’t require further specialization. But if you use GitHub Pages to host your repository as described in this post should be handy to add the following bit to its POM file
A Maven build requires a master pom.xml referred to as aggregator file. The aggregator contains a list of the modules that compose the build (in this case plugins/fragments, features and update site defined before). Each module, in turn, needs to define the aggregator file as its parent in its <parent></parent> section. The aggregator file has no parent. Note that the properties defined in the aggregator are available to the modules that define it as a parent.
Create a General project and a pom.xml inside it (forget about any warning/error message for now). Update it accordingly to the Overview tab below
Run Maven build
Select the aggregator POM file and run it from the contextual menu Run As > Maven build… specifying “clean verify” as goals and adding –Dmaven.multiModuleProjectDirectory as JRE argument (see How to section). The Console View will list all the successful steps performed.
Test the plugin
- The plugins can be tested running an Eclipse target application which includes all the plugin in the workspace. This will test the local version of the plugins, not of packages distributed via the update site built by Maven.
- To test the update site run an Eclipse target application with “software install” enabled and add the URL of the published repository. If not yet public you can add the local folder of the repository created by Maven.
How to and Troubleshooting
Eclipse Tycho tutorial
Eclipse delta pack (legacy) Install for all platform
error -Dmaven.multiModuleProjectDirectory system property is not set. Check $M2_HOME environment variable and mvn script match.
maven build directory
GitHub branches, multiple branches checkout, multiple working dir