Building JOGL in Eclipse

From JogampWiki
Revision as of 00:08, 6 March 2011 by Wwalker (talk | contribs) (Updated to use the new all.ide target)
Jump to navigation Jump to search

Why build in Eclipse?

Building JOGL inside Eclipse lets you use the Eclipse debugger, profiler, and unit test framework. It also gives you useful editing features like auto-complete and red underlines for syntax errors.

Prerequisites

Before you can build JOGL in Eclipse, make sure you can build it from the command line. Then double-check these things:

  • Make sure you've got a JDK installed and set up properly.
    • Make sure JAVA_HOME is set to your JDK directory. You must use a JDK, not a JRE, because Ant needs $JAVA_HOME/lib/tools.jar.
    • Make sure the $JAVA_HOME/bin directory is on your PATH. You must use a JDK bin directory, not a JRE bin directory, because Ant needs $JAVA_HOME/bin/javac.
  • Delete the CLASSPATH variable from your system environment variables or .cshrc if it exists.
    • Having this set with random old JARs on it is one of the leading causes of build problems.
  • Make sure you've got Ant 1.8.0 or later installed.
  • Make sure ANT_HOME is set to your Ant installation directory.
  • Make sure ANT_HOME/bin is on your PATH.

Overview

To build JOGL in Eclipse, we'll set up Eclipse's JRE and Ant version, create Eclipse projects for the gluegen and jogl projects, then add Ant builders to those projects to invoke the JOGL command-line Ant build.

Switch workspace to the parent of gluegen and jogl

You need to set your Eclipse workspace to the parent directory of the gluegen and jogl projects. This tells Eclipse where to create its .metadata directory, where it will store your settings for this group of projects.

  • Click "File > Switch Workspace > Other...".
  • Click the "Browse..." button.
  • Navigate to the parent directory of the gluegen and jogl projects, select it, and click "OK".
  • Click "OK" to dismiss the Workspace Launcher dialog.

Set up Eclipse's JRE

Eclipse will already have some JRE installed, but we need to make sure that it's set up properly.

  • Click "Window > Preferences", then select "Java > Installed JREs" on the left.
  • Select the checked JRE on the right, then click the "Edit..." button.
  • Make sure the JRE home is set to the same directory that you've got JAVA_HOME set to in your environment. If it's not, click "Directory..." to change it.
    • This should be a JDK directory.
    • The list of JRE system libraries should show a list of $JAVA_HOME/jre/lib/*.jar entries.
  • Click the "Add External JARs..." button, navigate to the $JAVA_HOME/lib directory, select tools.jar, and click "OK".
  • Click "Finish" to close the Edit JRE dialog, and "OK" to close the Preferences dialog.

Update Eclipse's Ant version

Ant comes bundled inside Eclipse, but we need Ant 1.8 or later to build JOGL, and Eclipse 3.6 still contains Ant 1.7. So we tell Eclipse to use your local Ant installation when it launches Ant.

  • Click "Window > Preferences", then select "Ant > Runtime" on the left.
  • Look inside "Ant Home Entries" on the "Classpath" tab. If it shows files for Ant 1.8 or later, you don't need to change anything.
  • If your Ant is older than 1.8, click the "Ant Home..." button, navigate to your Ant home directory and click "Open".
  • Click the "Properties" tab, click "Add Property...", set the name to "java.home", and set the value to your $JAVA_HOME/jre directory. This is needed on Windows to get some paths in the Ant build correct.
  • Click "OK" to exit Preferences dialog.

Create an Ant user library

We've told Eclipse which version of Ant to launch for external builds, but JOGL also contains code that uses classes in the Ant JARs. So we also need a way to tell our projects where those JARs are.

  • Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
  • Click the "New..." button, type "Ant" for the library name, and click "OK".
  • Click the "Add JARs..." button, navigate to your $ANT_HOME/lib directory, select all the JARs inside, and click "Open".
  • Click "OK" to exit Preferences dialog.

Create an SWT user library

To build the SWT tests in JOGL, Eclipse needs to know where the SWT JAR files are.

  • Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
  • Click the "New..." button, type "SWT" for the library name, and click "OK".
  • Click the "Add JARs..." button, navigate to your jogl\make\lib\swt\your-platform directory, select swt-debug.jar, and click "Open".
  • Click "OK" to exit Preferences dialog.

Import the gluegen and jogl projects

The Eclipse project files for gluegen and jogl should have been checked out along with the source code, so you should be able to import the two projects.

  • Click "File > Import...", then select "General > Existing Projects into Workspace".
  • Click "Next".
  • Click "Browse", then select your workspace directory and click "OK".
  • Uncheck any projects in the list except gluegen and jogl.
  • Click "Finish".

Create the gluegen project (optional)

Since the gluegen project files are checked out along with the code, you shouldn't have to create them yourself. But just for reference, if you did have to create them for some reason, here's how to do it.

First we create the new gluegen project with default settings.

  • Select "File > New > Project...".
  • Expand "Java", click "Java Project", and click the "Next" button.
  • Set "gluegen" as the project name and click the "Next" button.
  • To the "Remove all generated resources" dialog, click "Yes".
  • Click "Finish". This creates the .project and .classpath files in the gluegen directory.

Next we set up the source paths for the project so Eclipse knows which Java files to build. When we created the project, Eclipse automatically found these, but it doesn't have all the properties set like we want them.

  • Right-click the "gluegen" project and select "Properties".
  • Select "Java Build Path", then click the "Source" tab.
  • Click "Allow output folders for source folders". This allows the Java files in each source folder to be compiled to a different output folder, which we need to match the Ant build.
  • Set the default output folder to gluegen/build/classes.
  • Set the output folders, excluded patterns, and native library locations to the values in this table. Remove any source path entries that are not in this list.
source native output excluding
build/gensrc/java gluegen/build/obj build/classes
build/test/build/gensrc/classes gluegen/build/obj build/test/build/classes
src/java gluegen/build/obj build/classes com/jogamp/gluegen/runtime/BufferFactoryInternal.java
src/junit gluegen/build/obj build/test/build/classes
test/junit gluegen/build/obj build/test/build/classes com/jogamp/gluegen/StructValidator.java

Now we set up the libraries that are needed to build the project.

  • Click the "Libraries" tab.
  • Remove all the JARs except gluegen/make/lib/antlr.jar from the list.
  • Click "Add Library...", select "JUnit", click "Next", select "JUnit 4", and click "Finish".
  • The JRE System Library should already be on this list. If it's not, click "Add Library...", select "JRE System Library", click "Next", and click "Finish".
  • Click "Add Library...", select "User Library", click "Next", check "Ant", and click "Finish".
  • Click "OK" to dismiss the Properties dialog.

Finally we can set up the Ant builder. This lets Eclipse invoke our command-line Ant build.

  • Right-click the "gluegen" project, select "Properties".
  • Click the "Builders" tab on the left.
  • Uncheck the "Java Builder". Click "OK" when it asks you to confirm. This is needed to prevent Eclipse from rebuilding class files that the Ant builder is responsible for.
  • Click the "New..." button, select "Ant Builder", and click "OK".
  • Type "gluegen builder" as the name.
  • Set the buildfile to ${workspace_loc:/gluegen/make/build.xml}
  • Set the base directory to ${workspace_loc:/gluegen/make}
  • Click the "Refresh" tab, check "Refresh resources upon completion", click "The project containing the selected resource".
  • Click the "Targets" tab.
  • Click the "Set Targets..." button to the right of "Auto Build". Then check "all" and click "OK".
  • Click the "Set Targets..." button to the right of "During a "Clean"". Then uncheck "all", check "clean", and click "OK".
  • Click "OK" to dismiss the Edit Configuration dialog.
  • Select "gluegen builder" and click the "Up" button. This makes the Ant build go before Eclipse, which is necessary because the Ant build creates some source files.
  • Click "OK" to save and dismiss the Properties dialog. This creates the .externalToolBuilders directory in the glugen project.

Create the jogl project (optional)

Since the jogl project files are checked out along with the code, you shouldn't have to create them yourself. But just for reference, if you did have to create them for some reason, here's how to do it.

To create the jogl project, we do exactly what we did to create the gluegen project, but with different names and paths substituted. First we create the new jogl project with default settings.

  • Select "File > New > Project...".
  • Expand "Java", click "Java Project", and click the "Next" button.
  • Set "jogl" as the project name and click the "Next" button.
  • To the "Remove all generated resources" dialog, click "Yes".
  • Click "Finish".

Next we set up the source directories for the project.

  • Right-click the "jogl" project and select "Properties".
  • Select "Java Build Path", then click the "Source" tab.
  • Click "Allow output folders for source folders".
  • Set the default output folder to jogl/build/jogl/classes.
  • Set the output folders, excluded patterns, and native library locations to the values in this table. Remove any source path entries that are not in this list.
source native output excluding
build/jogl/gensrc/classes jogl/build/jogl/obj build/jogl/classes
build/nativewindow/gensrc/classes jogl/build/nativewindow/obj build/nativewindow/classes
src/jogl/classes jogl/build/jogl/obj build/jogl/classes com/jogamp/audio/windows/waveout/TestSpatialization.java, jogamp/opengl/gl2/fixme/
src/nativewindow/classes jogl/build/nativewindow/obj build/nativewindow/classes
src/newt/classes jogl/build/newt/obj build/newt/classes
src/test build/test/build/classes

The jogl project depends on the gluegen project being built first, so we need to set the dependency between them.

  • Click the "Projects" tab, click "Add...", check "gluegen", click "OK".

Now we set up the libraries that are needed to build the project.

  • Click the "Libraries" tab.
  • Remove all the JARs from the list.
  • Click "Add Library...", select "JUnit", click "Next", select "JUnit 4", and click "Finish".
  • The JRE System Library should already be on this list. If it's not, click "Add Library...", select "JRE System Library", click "Next", and click "Finish".
  • Click "Add Library...", select "User Library", click "Next", check "Ant" and "SWT", and click "Finish".
  • Click "OK" to dismiss the Properties dialog.

Finally we can set up the Ant builder.

  • Right-click the "jogl" project, select "Properties".
  • Click the "Builders" tab on the left.
  • Uncheck the "Java Builder". Click "OK" when it asks you to confirm. This is needed to prevent Eclipse from rebuilding class files that the Ant builder is responsible for.
  • Click the "New..." button, select "Ant Builder", and click "OK".
  • Type "jogl builder" as the name.
  • Set the buildfile to ${workspace_loc:/jogl/make/build.xml}
  • Set the base directory to ${workspace_loc:/jogl/make}
  • Click the "Refresh" tab, check "Refresh resources upon completion", click "The project containing the selected resource".
  • Click the "Targets" tab.
  • Click the "Set Targets..." button to the right of "After a "Clean"". Then uncheck "all", check "all.ide", and click "OK".
  • Click the "Set Targets..." button to the right of "Manual Build". Then uncheck "all", check "all.ide", and click "OK".
  • Click the "Set Targets..." button to the right of "Auto Build". Then check "all.ide" and click "OK".
  • Click the "Set Targets..." button to the right of "During a "Clean"". Then uncheck "all", check "clean", click "OK".
  • Click "OK" to dismiss the Edit Configuration dialog.
  • Select "jogl builder" and click the "Up" button.
  • Click "OK" to save and dismiss the Properties dialog.

Now we can clean and build both projects in Eclipse.

  • Select "Project > Clean", click "Clean all projects" and click "OK".

Install EGit in Eclipse

After the build works we can install EGit in Eclipse. This lets you perform Git source control operations from inside Eclipse, though it doesn't yet support every feature of the command line version.

Associate Eclipse projects with Git

After we install EGit, we have to tell Eclipse that gluegen and jogl are Git projects.

  • Right-click "gluegen", select "Team > Share Project...", select "Git", click "Next", select the .git repository, and click "Finish".
  • Do the same thing for the "jogl" project.

Now when you right-click projects or files in the Package Explorer, you can see the Git operations in the "Team" menu.