Building JOGL in Eclipse: Difference between revisions

From JogampWiki
Jump to navigation Jump to search
(First complete version)
No edit summary
 
(30 intermediate revisions by 2 users not shown)
Line 5: Line 5:
= Prerequisites =
= Prerequisites =


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


* Make sure you've got a JDK installed and set up properly.
* to have at least Eclipse Neon 2, that comes with Ant 1.9.6 (jogl requires 1.8+)
** Make sure the JDK bin directory is on your PATH.
* to have a JDK installed and set up properly.
*** You must use a JDK bin directory, not a JRE bin directory, because Ant needs javac.exe.
** <tt>JAVA_HOME</tt> is set to your JDK directory. You must use a JDK, not a JRE, because Ant needs <tt>$JAVA_HOME/lib/tools.jar</tt> (on Windows and Linux).
** Make sure JAVA_HOME is set to your JDK directory.
** <tt>$JAVA_HOME/bin</tt> directory is on your PATH. You must use a JDK bin directory, not a JRE bin directory, because Ant needs <tt>$JAVA_HOME/bin/javac</tt>.
*** You must use a JDK, not a JRE, because Ant needs lib\tools.jar.
* to delete the CLASSPATH variable from your system environment variables, <tt>.cshrc</tt>, <tt>.bash_profile</tt> or other location.
* Delete the CLASSPATH variable if it exists.
** having this set with random old JARs on it is one of the leading causes of build problems.
** Having this set with random old JARs on it is one of the leading causes of build problems.
* Make sure ANT_HOME is set to your Ant installation directory.
* Make sure ANT_HOME\bin is on your PATH.


= Overview =
= Overview =


To build JOGL in Eclipse, we'll create Eclipse projects for the gluegen and jogl projects, then add Ant builders to those projects to invoke the JOGL command-line Ant build.
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.


= Update Eclipse's Ant version =
= Set up Eclipse's workbench VM =


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 point at your local Ant installation.
The workbench VM is the version of Java that Eclipse uses to launch itself. Eclipse can find a Java VM on its own by looking in your system's default locations, but we don't want that, because it might pick a JRE instead of a JDK, which won't work with the JOGL Ant build.


* On the "Classpath" tab, click "Window > Preferences" and select "Ant > Runtime".
* Go to your Eclipse installation directory, and edit the <tt>eclipse.ini</tt> file (on Mac OS X, it's at <tt>&lt;eclipse installation directory&gt;/Eclipse.app/Contents/MacOS/eclipse.ini</tt>).
* 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 they don't exist already, add these lines before the <tt>-vmargs</tt> line.
* If your Ant is older than 1.8, click the "Ant Home..." button, navigate to your Ant home directory and click "Open".
Windows:
* Click the "Properties" tab, click "Add Property...", set the name to "java.home", and set the value to your JDK's "jre" directory. This is needed on Windows to get some paths in the Ant build correct.
<pre>
* Click "OK" to exit Preferences dialog.
-vm
<your JAVA_HOME directory>\jre\bin\javaw.exe
</pre>
Linux and Mac OS X:
<pre>
-vm
<your JAVA_HOME directory>/jre/bin/java
</pre>
* Save and close the file.
* If Eclipse is running, you must restart it for the setting to take effect.


= Create the gluegen project =
If you haven't done this step, the <tt>javah</tt> task may fail in the Ant build.
 
= Switch workspace to the parent of gluegen and jogl =
 
If you have already the usual configuration:
 
  /eclipse/workpace/
                    gluegen/
                    jogl/
 
Then you are fine. If not, you need to set your Eclipse workspace to the parent directory of the gluegen and jogl projects. This tells Eclipse where to create its <tt>.metadata</tt> directory, where it will store your settings for this group of projects.
 
* Click '''File''' > '''Switch Workspace''' > '''Other...''' and then '''Browse...'''
* 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 project JRE =
 
This is the version of Java that Eclipse runs and debugs your projects with. Eclipse will already have some project JRE installed, but we need to make sure that it's set up properly.
 
* Click '''Window''' > '''Preferences''' (it's '''Eclipse''' > '''Preferences...''' on Mac OS X), then '''Java''' > '''Installed JREs''' on the left
* Select the checked JRE on the right, then click '''Edit...'''
* Make sure the JRE home is set to the same directory that you've got <tt>JAVA_HOME</tt> 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 <tt>$JAVA_HOME/jre/lib/*.jar</tt> entries (on Windows and Linux) or a list of <tt>$JAVA_HOME/../Contents/Classes/*.jar</tt> entries (on Mac OS X)
* Click '''Finish''' to close the Edit JRE dialog, and '''OK''' to close the Preferences dialog
 
= Create an Ant user library =
 
JOGL contains code that uses classes in the Ant JARs. So we need a way to tell our projects where those JARs are.
 
* we need to know where the Ant bundled with Eclipse is, click '''Window''' > '''Preferences''' (it's '''Eclipse''' > '''Preferences...''' on Mac OS X) > '''Ant''' > '''runtime'''. In '''Classpath''' tab, expand '''Ant Home Entries''' and annotate down its path, this is your ''antHome''
* Select '''Java''' > '''Build Path''' > '''User Libraries''' on the left
* Click '''New...''', type ''Ant'' for the library name, and click '''OK'''
* Click '''Add JARs...''', navigate to your <tt>''antHome''/lib</tt> 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''' (it's '''Eclipse''' > '''Preferences...''' on Mac OS X), then '''Java''' > '''Build Path''' > '''User Libraries''' on the left
* Click '''New...''', type ''SWT'' for the library name, and click '''OK'''
* Click '''Add External JARs...''' button, navigate to your <tt>jogl\make\lib\swt\your-platform</tt> directory, select <tt>swt-debug.jar</tt>, 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''' and '''Browse''', then select your workspace directory and click '''OK'''
* Uncheck any projects in the list except gluegen and jogl and 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.
First we create the new gluegen project with default settings.


* Select "File > New > Project...".
* Select '''File''' > '''New''' > '''Java Project...'''
* Expand "Java", click "Java Project", and click the "Next" button.
* Set ''gluegen'' as the project name and click the '''Next'''
* Set "gluegen" as the project name and click the "Next" button.
* Click '''Finish'''. This creates the <tt>.project</tt> and <tt>.classpath</tt> files in the <tt>gluegen</tt> directory
* 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.
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".
* Right-click the ''gluegen'' project and select '''Properties'''
* Select "Java Build Path", then click the "Source" tab.
* Select '''Java Build Path''', then click the '''Source''' tab and remove any entry you find
* 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.
* At the bottom, 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 '''Default output folder''' to <tt>gluegen/build/classes</tt>
* 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.
* For each entry in this table, click '''Link Source''', browser to the right location as the ''Source folder location'' field in the table below, choose a proper name (you may want to substitute <tt>/</tt> with <tt>_</tt>) then '''Finish'''. Set also ''Output folder'', ''Excluded'' and ''Native library location'' accordingly
 
Pay attention of empty spaces if you copy/paste from the table!


{| border="1"
{| border="1"
! source
! Source folder location
! native
! Native library location
! output
! Output folder
! excluding
! Excluded
|-
|-
| build/gensrc/java
| build/gensrc/java
| gluegen/build/obj
| gluegen/build/obj
| build/classes
| (Default output folder)
|
|
|-
|-
Line 67: Line 129:
| src/java
| src/java
| gluegen/build/obj
| gluegen/build/obj
| build/classes
| (Default output folder)
| com/jogamp/gluegen/runtime/BufferFactoryInternal.java
| com/jogamp/gluegen/runtime/BufferFactoryInternal.java
|-
|-
Line 83: Line 145:
Now we set up the libraries that are needed to build the project.
Now we set up the libraries that are needed to build the project.


* Click the "Libraries" tab.
* Click the '''Libraries''' tab and remove all the JARs except <tt>"JRE System Library"</tt> from the list.
* Remove all the JARs except "gluegen/make/lib/antlr.jar" from the list.
* Click '''Add Library...''', select '''JUnit''', click '''Next''', select '''JUnit 4''' and then click '''Finish'''
* Click "Add Library...", select "JUnit", click "Next", select "JUnit 4", and click "Finish".
* Click '''OK''' to dismiss the Properties dialog
* 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 External JARs...", select ant.jar from your Ant installation's lib dir, click "Open".
* Click "Add External JARs...", select tools.jar from your JDK installation's lib directory, click "Open".
* Click "OK" to dismiss the Properties dialog.


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


* Right-click the "gluegen" project, select "Properties".
* Right-click the ''gluegen'' project, select '''Properties''' and click the '''Builders''' tab on the left
* 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".
* Click '''New...''', select '''Ant Builder''' and click '''OK'''
* Type "gluegen builder" as the name.
* Type ''gluegen builder'' as the name, then set the ''Buildfile'' to <tt>/gluegen/make/build.xml</tt> and the ''Base Directory'' to <tt>/gluegen/make</tt>
* Set the buildfile to "${workspace_loc:/gluegen/make/build.xml}" (without the quotes).
* Click '''Refresh''' tab, check '''Refresh resources upon completion''', click '''The project containing the selected resource'''
* Set the base directory to "${workspace_loc:/gluegen/make}" (without the quotes).
* Click '''Targets''' tab
* Click the "Refresh" tab, check "Refresh resources upon completion", click "The project containing the selected resource".
* Click '''Set Targets...''' to the right of ''Auto Build'' and control '''all''' is checked
* Click the "Targets" tab, click the "Set Targets..." button to the right of "During a "Clean".
* Click '''Set Targets...''' to the right of ''During a "Clean"''. Then uncheck '''all''', check '''clean''' and click '''OK'''
* Uncheck "all", check "clean", click "OK".
* Click '''OK''' to dismiss the Edit Configuration dialog
* Click "OK" to dismiss the Edit Configuration dialog.
* Click '''OK''' to save and dismiss the Properties dialog. This creates the <tt>.externalToolBuilders</tt> directory in the glugen project
* 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) =


= Create the jogl project =
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.
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...".
* Select '''File''' > '''New''' > '''Java Project...'''
* Expand "Java", click "Java Project", and click the "Next" button.
* Set ''jogl'' as the project name, click '''Next''' and then '''Finish'''
* 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.
Next we set up the source directories for the project.


* Right-click the "jogl" project and select "Properties".
* Right-click the ''jogl'' project and select '''Properties'''
* Select "Java Build Path", then click the "Source" tab.
* Select '''Java Build Path''', then click '''Source''' tab and remove any entry you find
* Click "Allow output folders for source folders".
* At the bottom, click '''Allow output folders for source folders''' and set '''Default output folder''' to <tt>jogl/build/jogl/classes</tt>
* Set the default output folder to "jogl/build/jogl/classes".
* For each entry in this table, click '''Link Source''', browser to the right location as the ''Source folder location'' field in the table below, choose a proper name (you may want to substitute <tt>/</tt> with <tt>_</tt>) then '''Finish'''. Set also ''Output folder'', ''Excluded'' and ''Native library location'' accordingly
* 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.
 
Pay attention of empty spaces if you copy/paste from the table!


{| border="1"
{| border="1"
! source
! Source folder location
! native
! Native library location
! output
! Output folder
! excluding
! Excluded
|-
|-
| build/jogl/gensrc/classes
| build/jogl/gensrc/classes
| jogl/build/lib
| jogl/build/jogl/obj
| build/jogl/classes
| (Default output folder)
|
|
|-
|-
| build/nativewindow/gensrc/classes
| build/nativewindow/gensrc/classes
| jogl/build/lib
| jogl/build/nativewindow/obj
| build/nativewindow/classes
| build/nativewindow/classes
|
|
|-
|-
| src/jogl/classes
| src/jogl/classes
| jogl/build/lib
| jogl/build/jogl/obj
| build/jogl/classes
| (Default output folder)
| com/jogamp/audio/windows/waveout/TestSpatialization.java, com/jogamp/opengl/impl/gl2/fixme/**
| com/jogamp/audio/windows/waveout/TestSpatialization.java, jogamp/opengl/gl2/fixme/
|-
|-
| src/nativewindow/classes
| src/nativewindow/classes
| jogl/build/lib
| jogl/build/nativewindow/obj
| build/nativewindow/classes
| build/nativewindow/classes
|
|
|-
|-
| src/newt/classes
| src/newt/classes
| jogl/build/lib
| jogl/build/newt/obj
| build/newt/classes
| build/newt/classes
|
|
|-
|-
| src/test
| src/test
| jogl/build/lib
|
| build/test/build/classes
| build/test/build/classes
|
|
Line 162: Line 218:


The jogl project depends on the gluegen project being built first, so we need to set the dependency between them.
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".
* Click the '''Projects''' tab, '''Add...''', check ''gluegen'' and click '''OK'''


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


* Click the "Libraries" tab.
* Click '''Libraries''' tab and remove all the JARs from the list except <tt>"JRE System Library"</tt>
* Remove all the JARs from the list.
* Click '''Add Library...''', select '''JUnit''', click '''Next''', select '''JUnit 4''' and click '''Finish'''
* Click "Add Library...", select "JUnit", click "Next", select "JUnit 4", and click "Finish".
* Click '''Add Library...''', select '''User Library''', click '''Next''', check '''Ant''' and '''SWT''' 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 '''OK''' to dismiss the Properties dialog
* Click "Add External JARs...", select ant.jar from your Ant installation's lib dir, click "Open"
* Click "Add External JARs...", select ant-junit.jar from your Ant installation's lib dir, click "Open"
* Click "OK" to dismiss the Properties dialog


Finally we can set up the Ant builder.
Finally we can set up the Ant builder.


* Right-click the "jogl" project, select "Properties".
* Right-click the ''jogl'' project, select '''Properties''' and click the '''Builders''' tab on the left
* Click the "Builders" tab on the left.
* Uncheck the '''Java Builder''' and 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".
* Click '''New...''' button, select '''Ant Builder''' and click '''OK'''
* Type "jogl builder" as the name.
* Type ''jogl builder'' as the name and set ''Buildfile'' to <tt>jogl/make/build.xml</tt> and ''Base Directory'' to <tt>jogl/make</tt>
* Set the buildfile to "${workspace_loc:/jogl/make/build.xml}" (without the quotes).
* Click '''Refresh''' tab, check '''Refresh resources upon completion''', click '''The project containing the selected resource'''
* Set the base directory to "${workspace_loc:/jogl/make}" (without the quotes).
* Click '''Targets''' tab
* Click the "Refresh" tab, check "Refresh resources upon completion", click "The project containing the selected resource".
* For the first three elements (''After a "Clean"'', ''Manual Build'' and ''Auto Build'') now uncheck everything and check '''all.ide''' as target
* Click the "Targets" tab, click the "Set Targets..." button to the right of "During a "Clean".
* Click '''Set Targets...''' to the right of ''During a "Clean"'', uncheck '''all''', check '''clean''' and click '''OK'''
* Uncheck "all", check "clean", click "OK".
* Click '''OK''' to dismiss the Edit Configuration dialog and again '''OK''' to save and dismiss the Properties dialog
* 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.
Now we can clean and build both projects in Eclipse.


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


= Install EGit in Eclipse =
= Install EGit in Eclipse (Eclipse 3.6 and earlier) =


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.
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. EGit is pre-installed in Eclipse 3.7 and later, so check your Eclipse version before doing this.


* Click "Help > Install New Software..."
* Click "Help > Install New Software...".
* Type "http://download.eclipse.org/egit/updates" in the "Work with" box and press enter
* Type <tt>http://download.eclipse.org/egit/updates</tt> in the "Work with" box and press enter.
* Check "Eclipse EGit" and "Eclipse JGit" and install
* Check "Eclipse Git Team Provider" and "Eclipse JGit" and install them.


= Associate Eclipse projects with Git =
= Associate Eclipse projects with Git =
Line 205: Line 255:
After we install EGit, we have to tell Eclipse that gluegen and jogl are Git projects.
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, click "Finish"
* 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
* 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.
Now when you right-click projects or files in the Package Explorer, you can see the Git operations in the "Team" menu.

Latest revision as of 23:42, 5 February 2017

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:

  • to have at least Eclipse Neon 2, that comes with Ant 1.9.6 (jogl requires 1.8+)
  • to have a JDK installed and set up properly.
    • JAVA_HOME is set to your JDK directory. You must use a JDK, not a JRE, because Ant needs $JAVA_HOME/lib/tools.jar (on Windows and Linux).
    • $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.
  • to delete the CLASSPATH variable from your system environment variables, .cshrc, .bash_profile or other location.
    • having this set with random old JARs on it is one of the leading causes of build problems.

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.

Set up Eclipse's workbench VM

The workbench VM is the version of Java that Eclipse uses to launch itself. Eclipse can find a Java VM on its own by looking in your system's default locations, but we don't want that, because it might pick a JRE instead of a JDK, which won't work with the JOGL Ant build.

  • Go to your Eclipse installation directory, and edit the eclipse.ini file (on Mac OS X, it's at <eclipse installation directory>/Eclipse.app/Contents/MacOS/eclipse.ini).
  • If they don't exist already, add these lines before the -vmargs line.

Windows:

-vm
<your JAVA_HOME directory>\jre\bin\javaw.exe

Linux and Mac OS X:

-vm
<your JAVA_HOME directory>/jre/bin/java
  • Save and close the file.
  • If Eclipse is running, you must restart it for the setting to take effect.

If you haven't done this step, the javah task may fail in the Ant build.

Switch workspace to the parent of gluegen and jogl

If you have already the usual configuration:

  /eclipse/workpace/
                    gluegen/
                    jogl/

Then you are fine. If not, 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... and then Browse...
  • 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 project JRE

This is the version of Java that Eclipse runs and debugs your projects with. Eclipse will already have some project JRE installed, but we need to make sure that it's set up properly.

  • Click Window > Preferences (it's Eclipse > Preferences... on Mac OS X), then Java > Installed JREs on the left
  • Select the checked JRE on the right, then click Edit...
  • 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 (on Windows and Linux) or a list of $JAVA_HOME/../Contents/Classes/*.jar entries (on Mac OS X)
  • Click Finish to close the Edit JRE dialog, and OK to close the Preferences dialog

Create an Ant user library

JOGL contains code that uses classes in the Ant JARs. So we need a way to tell our projects where those JARs are.

  • we need to know where the Ant bundled with Eclipse is, click Window > Preferences (it's Eclipse > Preferences... on Mac OS X) > Ant > runtime. In Classpath tab, expand Ant Home Entries and annotate down its path, this is your antHome
  • Select Java > Build Path > User Libraries on the left
  • Click New..., type Ant for the library name, and click OK
  • Click Add JARs..., navigate to your antHome/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 (it's Eclipse > Preferences... on Mac OS X), then Java > Build Path > User Libraries on the left
  • Click New..., type SWT for the library name, and click OK
  • Click Add External 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 and Browse, then select your workspace directory and click OK
  • Uncheck any projects in the list except gluegen and jogl and 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 > Java Project...
  • Set gluegen as the project name and click the Next
  • 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 and remove any entry you find
  • At the bottom, 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
  • For each entry in this table, click Link Source, browser to the right location as the Source folder location field in the table below, choose a proper name (you may want to substitute / with _) then Finish. Set also Output folder, Excluded and Native library location accordingly

Pay attention of empty spaces if you copy/paste from the table!

Source folder location Native library location Output folder Excluded
build/gensrc/java gluegen/build/obj (Default output folder)
build/test/build/gensrc/classes gluegen/build/obj build/test/build/classes
src/java gluegen/build/obj (Default output folder) 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 and remove all the JARs except "JRE System Library" from the list.
  • Click Add Library..., select JUnit, click Next, select JUnit 4 and then 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 and 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 New..., select Ant Builder and click OK
  • Type gluegen builder as the name, then set the Buildfile to /gluegen/make/build.xml and the Base Directory to /gluegen/make
  • Click Refresh tab, check Refresh resources upon completion, click The project containing the selected resource
  • Click Targets tab
  • Click Set Targets... to the right of Auto Build and control all is checked
  • Click Set Targets... to the right of During a "Clean". Then uncheck all, check clean and click OK
  • Click OK to dismiss the Edit Configuration dialog
  • 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 > Java Project...
  • Set jogl as the project name, click Next and then 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 Source tab and remove any entry you find
  • At the bottom, click Allow output folders for source folders and set Default output folder to jogl/build/jogl/classes
  • For each entry in this table, click Link Source, browser to the right location as the Source folder location field in the table below, choose a proper name (you may want to substitute / with _) then Finish. Set also Output folder, Excluded and Native library location accordingly

Pay attention of empty spaces if you copy/paste from the table!

Source folder location Native library location Output folder Excluded
build/jogl/gensrc/classes jogl/build/jogl/obj (Default output folder)
build/nativewindow/gensrc/classes jogl/build/nativewindow/obj build/nativewindow/classes
src/jogl/classes jogl/build/jogl/obj (Default output folder) 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, Add..., check gluegen and click OK

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

  • Click Libraries tab and remove all the JARs from the list except "JRE System Library"
  • Click Add Library..., select JUnit, click Next, select JUnit 4 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 and click the Builders tab on the left
  • Uncheck the Java Builder and 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 New... button, select Ant Builder and click OK
  • Type jogl builder as the name and set Buildfile to jogl/make/build.xml and Base Directory to jogl/make
  • Click Refresh tab, check Refresh resources upon completion, click The project containing the selected resource
  • Click Targets tab
  • For the first three elements (After a "Clean", Manual Build and Auto Build) now uncheck everything and check all.ide as target
  • Click Set Targets... to the right of During a "Clean", uncheck all, check clean and click OK
  • Click OK to dismiss the Edit Configuration dialog and again 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 (Eclipse 3.6 and earlier)

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. EGit is pre-installed in Eclipse 3.7 and later, so check your Eclipse version before doing this.

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.