Use JOGL bundle in Mavenized build.

[leeca]

Hi Wade -

This is the name.wadewalker.tutorial pull-request that accompanies my earlier com.jogamp.jogl pull-request. This pull-request uses the JOGL bundle created by the com.jogamp.jogl build, and uses Tycho to complete the entire product build from the command line.

The Eclipse Tycho plugin for Maven uses the Eclipse PDE and OSGi MANIFEST.MF file to determine dependencies and to control the build. This means that Tycho builds are "Manifest First", and must be build after any "POM First" Maven builds. So JOGL builds in one Maven invocation, and the Tutorial product build is the second Maven run.

Since the JOGL libraries are constructed entirely from the POM, this build needs to complete before the Maven build of the tutorial. Fortunately, the JOGL libraries are in the separate org.jogampl.jogl Git repository, so this separate build is fairly natural. If is only needed once (per JOGL version).

The Tutorial build is organized as 4 Maven (and Eclipse) projects in the name.wadewalker.jogl repository. Tycho uses different packaging types for plugins and products, so that requires two projects (tutorial-plugin and tutorial-product). With a "build-line" layout, the tutorial-parent defines the shared build context and tutorial-master aggretates all the components for a product build.
To work with this projects in Eclipse, you only need to clone the two repositories and import all 5 of the projects. I recommend loading the one Eclipse project in com.jogamp.jogl first, since that seems to minimize the number of transient warning messages.

The current structure of the Tutorial application is ok for its scale, but it should be adapted for anything larger. Most importantly, the build should use a Target Definition (add a tutorial-target project) and build the product from Features, not Plugins (add a tutorial-feature project). These two capabilities add two more Maven packages to the infrastructure, and that's excessive for a simple Tutorial. It provides a great extensibiltiy foundation for multiple plugins and Eclipse contributions.

Thanks

• Lee ([email protected])

[leeca]

A full build and launch of this branch should be possible by executing with these commands at the top of the repository clone. Note that the com.jogamp.jogl Maven project must have been build previously.

git checkout --track origin/tycho
mvn -f tutorial-master clean install
./startTutorial.sh

[WadeWalker]

Hi Lee,

I don't know much about Maven, so I need to ask you some questions about this :) It seems like this makes Maven a requirement to build the project, is that true? For this simple tutorial project, I'm not sure I want to require users to use anything beyond vanilla Eclipse. Also, is it necessary to move the whole project into another directory in order for Maven to work? This makes your pull request touch every file in the project, which seems like a big change.

[leeca]

Hi Wade -

First off ... THANK YOU THANK YOU THANK YOU for solving JOGL in Eclipse
RCP. (I bet you get this all the time :-) ) I had been dreading having to
repackage JOGL platform libraries into a multi-feature multi-fragment
application build. It was such a relief to get JOGL working by providing a
new JarIUtil resolve() implementation. Now it runs on any JOGL platform
with zero code changes! This fix has been flawless (and amazing!). Thanks
again.

Thank you also for taking the time to look at the Mavenized version of your
tutorial. I've been working to Mavenize my DepAn RCP application (6 3rd
party library, incl JOGL, 6 plugins, 4 features, and growing). This
complexity, especially JOGL, meant that generating a releasable set of bits
required hand-crafted PDE builds and it was nearly impossible to upgrade
any component. Now, I only need to change a version property in the parent
file and everything is good. No finding the current download site, or any
of the other craziness of supporting a product for years.

I do assume that Maven was widely available to any Java developer. For
quite a while now, Maven support has been baked into Eclipse through the
m2e plugin. And Tycho is a "standard" Maven plugin, so Eclipse and Maven
mostly play well together. But you are right that "widely available" isn't
exactly true. I did have to install the command line version myself. I do
think Maven is destined to become part of the state-of-the-practice
tool-chain. Hopefully, pushing "make" into the pasture :-). But perhaps
Maven is not quite as pervasive as I assumed.

I did not do the experiment, but I would have expected an internal Eclipse
PDE/Product Build to be successful. All of the PDE artifacts remain in
place, so these components should build. I did test running the tutorial
within the Eclipse Debugger, and that did seem to work fine. If you are
having trouble with this, I'd be glad to provide some assistance.

I would not be surprised if the JOGL bundle needs to be built with Maven
separately from using the Eclipse projects. There is probably a way to
"dual source" the bundle. One thing you might notice in the Maven
generated bundle is that the exposed API (listed as ) is
much narrower in the Maven bundle versus your original MANIFEST.MF. I think
I have it restricted to just the public APIs. One of the niceties of the
JOGL bundling is that the project does not directly include any of the JOGL
release files. These are all pulled from the standard Maven repository.
No manual unzipping required.

I understand that moving all the plugin source code down a level makes the
change bigger then necessary. With Eclipse PDE, the Tutorial.product can
harmlessly "hide-out" in the single-plugin's project. However, Maven +
Tycho expects the product build to be its own Maven project. Once the
tutorial-product project comes into existence, it's hard to avoid using a
tutorial-plugin project - it's good to have a tutorial-parent that sets the
shared build environment, etc. This architecture, with the tutorial-master
aggregating all the Maven projects, works well for flat-project models that
Eclipse favors. (There are hierarchical Maven architectures that use one
less project, but these have dependency issues and the tutorial's source
code would be two levels lower, not one.)

I agree that the simplicity of a single project for the tutorial
demonstration is very desirable. However, its also non-trivial to convert
the tutorial into a buildable, scalable application. I felt that having a
Maven-ready version of your JOGL Tutorial was a good way to give back to
the open-source community. It's a simple as I could make it, but the Maven
infrastructure does add a bunch of distractions.

Since you are THE MAN - the go-to guy for JOGL + Eclipse integration - I
thought it would be useful to update the tutorial for modern build tools.
As you note in your blog, JOGL and Eclipse have changed tons since 2010,
and standard Java practice continues to evolves. (How do you like Java
8?). I get that the added complexity of the Mavenized version could be
off-putting. Perhaps these changes should be left as a separate branch
with some note added to the blog page. I guess I could just added a
comment at the end that references my repository forks.

As a bonus, I've tacked onto this note a simple analysis diagram generated
by my DepAn application. It should the classes defined by the
tutorial-plugin project. The arrows indicate that methods of one class
call a method in the other class. For the tutorial, this diagram shows a
clean design, with 2 independent sets of classes. I'd give this an A+.

Thanks again for solving JOGL within Eclipse, and for your time looking at
this pull request.

Let me know if you have any questions

• Lee

On Sun, Oct 25, 2015 at 7:34 AM, Wade Walker [email protected]
wrote:

Hi Lee,

I don't know much about Maven, so I need to ask you some questions about
this :) It seems like this makes Maven a requirement to build the project,
is that true? For this simple tutorial project, I'm not sure I want to
require users to use anything beyond vanilla Eclipse. Also, is it necessary
to move the whole project into another directory in order for Maven to
work? This makes your pull request touch every file in the project, which
seems like a big change.

—
Reply to this email directly or view it on GitHub
#1 (comment)
.

[WadeWalker]

Hi Lee,

Thanks for the kind words :) I don't know if I'm ready to switch over to Maven and Tycho yet myself, but I do think you're right that it's valuable to have those versions of JOGL and my tutorial available. I've got no objection if you want to put them on your own GitHub page; I can even amend my project descriptions to point people to them if they're interested.

Right now I'm in the midst of getting Java OpenCL up to date with the latest OpenCL version, and after that I'll probably update my tutorial some more to show how to use JOGL, JOCL, and Eclipse RCP together.