JogampWiki - User contributions [en]

Maven

2015-10-31T22:46:52Z

Mraynsford: Fat jars!

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.3.1</tt>:

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.3.1</version>
</dependency>
</dependencies>
</pre>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.3.1</version>
</dependency>
</dependencies>
</pre>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.3.1/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<pre>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.3.1</version>
</dependency>
</pre>

Maven would download <tt>jogl-all-2.3.1.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the package where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.3.1/jogl-all-main-2.3.1.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.joal
|joal-android
|2.2.0
|JOAL Android runtime
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl-android
|2.2.0
|JOCL Android runtime
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-android-main
|2.2.0
|Meta-package for automatic dependency resolution for JOGL (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|2.0.2
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|2.0.2
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|nativewindow-main
|2.2.0
|Native window drivers for NEWT (atomic frontend)
|-
|org.jogamp.jogl
|newt
|2.0.2
|NEWT code and native libraries (atomic jars)
|-
|org.jogamp.jogl
|newt-main
|2.2.0
|NEWT code and native libraries (atomic frontend)
|-
|org.jogamp.jogl
|occulusvr
|2.2.0
|JOGL code and native libraries (Oculus VR atomic jar files)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<pre>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.3.1</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.3.1</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.3.1</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.3.1</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.3.1</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.3.1</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.3.1</version>
<classifier>driver-x11</classifier>
</dependency>
</pre>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</pre>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

= Android =

There is a [[Maven_And_Android|separate page]] documenting one method of producing packages that work on both Android and ordinary
desktop Java.

= Producing a fat jar =

See [[JogAmp_JAR_File_Handling#Maven_Assembly_Plugin|JAR File Handling]].

Maven

2015-10-31T22:43:56Z

Mraynsford: Do not use <code> tags, as their formatting now appears to be broken

JogAmp JAR File Handling

2015-10-31T21:05:03Z

Mraynsford: Close your damn parens

= Native JAR Files =

See [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFiles Native JAR Files] explained.

Native JAR files are loaded [{{SERVER}}/jogl/doc/userguide/index.html#automatednativelibraryloading automatically].

= Applet / JNLP Usage =

* [[Using JOGL in a Java applet|Using JOGL in a Java Applet]]
* [[Using JOGL in Java Web Start|Using JOGL in Java Web Start]]

A short ''copy'' is included in the static page [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NApplets JOGL Deployment using NApplet].

= Custom Bundling =

== Multi-Jar ==
[{{SERVER}}/bugzilla/show_bug.cgi?id=843 Multi-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

However, since we don't want to patronize our user base, we support this feature with our native JAR lib loading mechanism.

It is possible to merge all modules together, i.e.

multi.jar:
gluegen-rt.jar
jogl-all.jar
user-app.jar

multi-natives-<os.and.arch>.jar:
gluegen-rt-natives-<os.and.arch>.jar
jogl-all-natives-<os.and.arch>.jar

A combination with Fat-Jar is possible.

== Fat-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=845 Discouraged Fat-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

Furthermore, adding all native library files for all supported platforms
will add-up to +3M of _compressed_ jar data!

However, since we don't want to patronize our user base,
we support this feature with our native JAR lib loading mechanism.

=== Usage ===

If the modules's jar file contains the folder 'natives/<os.and.arch>/'
we assume a fat-jar and attempt to load all native libraries from the same.

If we don't have a fat-jar or if fat-jar loading doesn't result in extracted native libraries,
we assume a regular slim jar file.

Layout:

/com/lala1/Lala1.class
/com/lala2/Lala2.class
/natives/<os.and.arch>/libLala1.so
/natives/<os.and.arch>/libLala2.so

A combination w/ Multi-Jar is of course possible.

=== Creation ===

==== Ant ====
You can use the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task] to create a fat JAR. You must avoid file names collision, i.e you must exclude the file(s) with the same name(s) in multiple JARs. You can use [https://ant.apache.org/manual/Tasks/manifest.html Ant manifest task] to create a manifest file. The following line just keeps the strict minimum to make JogAmp work and should be used with the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task]:

<zipfileset src="jogamp-fat.jar" includes="**/*.class,**/*.png,**/*.glsl,**/*.vp,**/*.fp,**/*.bvp,**/*.bfp,**/*.so,**/*.jnilib,**/*.dylib,**/*.dll,**/.bin"/>

==== Maven ====
[http://maven.apache.org/plugins/maven-shade-plugin/index.html Maven Shade Plugin] is the recommended plugin to use to create fat JARs with [http://maven.apache.org Maven]. [http://maven.apache.org/plugins/maven-shade-plugin/examples/executable-jar.html This example] shows how to set some entries in the manifest file.

==== Maven Assembly Plugin ====

An example descriptor file that produces a fat jar containing all of the calling project's dependencies, and the JOGL/GlueGen native jar files placed into the correct directory inside the jar:

<pre>
<assembly
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">

<id>with-dependencies</id>
<includeBaseDirectory>false</includeBaseDirectory>

<formats>
<format>jar</format>
</formats>

<dependencySets>


<dependencySet>
<outputDirectory>/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<unpackOptions>
<excludes>
<exclude>libgluegen-rt*</exclude>
<exclude>libjogl_desktop.*</exclude>
<exclude>libjogl_mobile.*</exclude>
<exclude>libnativewindow_awt.*</exclude>
<exclude>libnativewindow_macosx.*</exclude>
<exclude>libnativewindow_x11.*</exclude>
<exclude>libnewt.*</exclude>
</excludes>
</unpackOptions>
</dependencySet>




<dependencySet>
<outputDirectory>/natives/linux-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/linux-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-i586</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-i586</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/macosx-universal/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-macosx-universal</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-macosx-universal</include>
</includes>
<unpackOptions>
<includes><include>*.jnilib</include></includes>
</unpackOptions>
</dependencySet>
</dependencySets>
</assembly>
</pre>

This can be called in the usual manner (assuming that the descriptor file is in <tt>src/main/assembly/application.xml</tt>):

<pre>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<archive>
<manifest>
<mainClass>com.example.main.SomeMainClassHere</mainClass>
</manifest>
</archive>
<descriptors>
<descriptor>src/main/assembly/application.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</pre>

The result is an executable jar file, suffixed with <tt>-with-dependencies.jar</tt> that will execute <tt>com.example.main.SomeMainClassHere</tt> and that will correctly find all of the native libraries at run-time.

== One-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=846 One-Jar]

One-Jar is incomplete, i.e. it does not provide a URL handler for
it's jar-in-jar resources - hence we would need to implement this functionality manually.

See [{{SERVER}}/bugzilla/show_bug.cgi?id=846#c1 One-Jar lacks of URLHandler ...]

For now, one can use Eclipse working jar-in-jar feature (see below).
Since Eclipse is under an open source license, one should be able
to locate the source code and include in a standalone toolkit, if so required.

== JarMatey ==

[http://staticvoidgames.com/JarMatey/ JarMatey] is an [https://github.com/KevinWorkman/JarMatey open source] tool for creating standalone self-executing JARs, similar to One-Jar but with a graphical user interface and no support for build tools (Ant, Maven). You can find a detailed tutorial about it [http://staticvoidgames.com/tutorials/deployment/joglExample here].

== Eclipse ==

Native JAR files and their respective base JAR files can be bundled in [{{SERVER}}/bugzilla/show_bug.cgi?id=522#c7 custom ways, e.g. eclipse Jar-In-Jar etc].

Manual tested w/ Eclipse:

Preparations:
===============

1) Set up a vanilla eclipse (3.7.0) workspace

2) Add the JOGL User Library:
- Window.Preference
- Java.Build_Path.User_Libraries:
+ JOGL
+ gluegen-rt.jar
+ jogl-all.jar
+ gluegen-rt-natives-linux-amd64.jar
+ jogl-all-natives-linux-amd64.jar

You may add all other native JARs here.
Note that these are not required in the CLASSPATH by JOGL,
however, they are required by Eclipse to export your project as a Runnable JAR File.

3) New test project
- Right-click your project in the Package Explorer and click "Properties".
- Select "Java Build Path" and click the "Libraries" tab.
+ JOGL
- Add some simple code ..
- Run as Java Application ..

Test-1:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Copy required libraries into a sub-folder next to the generated JAR

Result: Works!

./lala01.jar
./lala01_lib/jogl-all.jar
./lala01_lib/jogl-all-natives-linux-amd64.jar
./lala01_lib/... etc ..

Test-2:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Package required libraries into generated JAR

Result: Works!

./lala02.jar:
Manifest-Version: 1.0
Rsrc-Class-Path: ./ gluegen-rt-natives-linux-amd64.jar gluegen-rt.jar
jogl-all-natives-linux-amd64.jar jogl-all.jar
Class-Path: .
Rsrc-Main-Class: Test01
Main-Class: org.eclipse.jdt.internal.jarinjarloader.JarRsrcLoader

JogAmp JAR File Handling

2015-10-31T20:57:36Z

Mraynsford: /* Maven Assembly Plugin */

= Native JAR Files =

See [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFiles Native JAR Files] explained.

Native JAR files are loaded [{{SERVER}}/jogl/doc/userguide/index.html#automatednativelibraryloading automatically].

= Applet / JNLP Usage =

* [[Using JOGL in a Java applet|Using JOGL in a Java Applet]]
* [[Using JOGL in Java Web Start|Using JOGL in Java Web Start]]

A short ''copy'' is included in the static page [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NApplets JOGL Deployment using NApplet].

= Custom Bundling =

== Multi-Jar ==
[{{SERVER}}/bugzilla/show_bug.cgi?id=843 Multi-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

However, since we don't want to patronize our user base, we support this feature with our native JAR lib loading mechanism.

It is possible to merge all modules together, i.e.

multi.jar:
gluegen-rt.jar
jogl-all.jar
user-app.jar

multi-natives-<os.and.arch>.jar:
gluegen-rt-natives-<os.and.arch>.jar
jogl-all-natives-<os.and.arch>.jar

A combination with Fat-Jar is possible.

== Fat-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=845 Discouraged Fat-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

Furthermore, adding all native library files for all supported platforms
will add-up to +3M of _compressed_ jar data!

However, since we don't want to patronize our user base,
we support this feature with our native JAR lib loading mechanism.

=== Usage ===

If the modules's jar file contains the folder 'natives/<os.and.arch>/'
we assume a fat-jar and attempt to load all native libraries from the same.

If we don't have a fat-jar or if fat-jar loading doesn't result in extracted native libraries,
we assume a regular slim jar file.

Layout:

/com/lala1/Lala1.class
/com/lala2/Lala2.class
/natives/<os.and.arch>/libLala1.so
/natives/<os.and.arch>/libLala2.so

A combination w/ Multi-Jar is of course possible.

=== Creation ===

==== Ant ====
You can use the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task] to create a fat JAR. You must avoid file names collision, i.e you must exclude the file(s) with the same name(s) in multiple JARs. You can use [https://ant.apache.org/manual/Tasks/manifest.html Ant manifest task] to create a manifest file. The following line just keeps the strict minimum to make JogAmp work and should be used with the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task]:

<zipfileset src="jogamp-fat.jar" includes="**/*.class,**/*.png,**/*.glsl,**/*.vp,**/*.fp,**/*.bvp,**/*.bfp,**/*.so,**/*.jnilib,**/*.dylib,**/*.dll,**/.bin"/>

==== Maven ====
[http://maven.apache.org/plugins/maven-shade-plugin/index.html Maven Shade Plugin] is the recommended plugin to use to create fat JARs with [http://maven.apache.org Maven]. [http://maven.apache.org/plugins/maven-shade-plugin/examples/executable-jar.html This example] shows how to set some entries in the manifest file.

==== Maven Assembly Plugin ====

An example descriptor file that produces a fat jar containing all of the calling project's dependencies, and the JOGL/GlueGen native jar files placed into the correct directory inside the jar:

<pre>
<assembly
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">

<id>with-dependencies</id>
<includeBaseDirectory>false</includeBaseDirectory>

<formats>
<format>jar</format>
</formats>

<dependencySets>


<dependencySet>
<outputDirectory>/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<unpackOptions>
<excludes>
<exclude>libgluegen-rt*</exclude>
<exclude>libjogl_desktop.*</exclude>
<exclude>libjogl_mobile.*</exclude>
<exclude>libnativewindow_awt.*</exclude>
<exclude>libnativewindow_macosx.*</exclude>
<exclude>libnativewindow_x11.*</exclude>
<exclude>libnewt.*</exclude>
</excludes>
</unpackOptions>
</dependencySet>




<dependencySet>
<outputDirectory>/natives/linux-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/linux-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-i586</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-i586</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/macosx-universal/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-macosx-universal</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-macosx-universal</include>
</includes>
<unpackOptions>
<includes><include>*.jnilib</include></includes>
</unpackOptions>
</dependencySet>
</dependencySets>
</assembly>
</pre>

This can be called in the usual manner (assuming that the descriptor file is in <tt>src/main/assembly/application.xml</tt>:

<pre>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<archive>
<manifest>
<mainClass>com.example.main.SomeMainClassHere</mainClass>
</manifest>
</archive>
<descriptors>
<descriptor>src/main/assembly/application.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</pre>

The result is an executable jar file, suffixed with <tt>-with-dependencies.jar</tt> that will execute <tt>com.example.main.SomeMainClassHere</tt> and that will correctly find all of the native libraries at run-time.

== One-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=846 One-Jar]

One-Jar is incomplete, i.e. it does not provide a URL handler for
it's jar-in-jar resources - hence we would need to implement this functionality manually.

See [{{SERVER}}/bugzilla/show_bug.cgi?id=846#c1 One-Jar lacks of URLHandler ...]

For now, one can use Eclipse working jar-in-jar feature (see below).
Since Eclipse is under an open source license, one should be able
to locate the source code and include in a standalone toolkit, if so required.

== JarMatey ==

[http://staticvoidgames.com/JarMatey/ JarMatey] is an [https://github.com/KevinWorkman/JarMatey open source] tool for creating standalone self-executing JARs, similar to One-Jar but with a graphical user interface and no support for build tools (Ant, Maven). You can find a detailed tutorial about it [http://staticvoidgames.com/tutorials/deployment/joglExample here].

== Eclipse ==

Native JAR files and their respective base JAR files can be bundled in [{{SERVER}}/bugzilla/show_bug.cgi?id=522#c7 custom ways, e.g. eclipse Jar-In-Jar etc].

Manual tested w/ Eclipse:

Preparations:
===============

1) Set up a vanilla eclipse (3.7.0) workspace

2) Add the JOGL User Library:
- Window.Preference
- Java.Build_Path.User_Libraries:
+ JOGL
+ gluegen-rt.jar
+ jogl-all.jar
+ gluegen-rt-natives-linux-amd64.jar
+ jogl-all-natives-linux-amd64.jar

You may add all other native JARs here.
Note that these are not required in the CLASSPATH by JOGL,
however, they are required by Eclipse to export your project as a Runnable JAR File.

3) New test project
- Right-click your project in the Package Explorer and click "Properties".
- Select "Java Build Path" and click the "Libraries" tab.
+ JOGL
- Add some simple code ..
- Run as Java Application ..

Test-1:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Copy required libraries into a sub-folder next to the generated JAR

Result: Works!

./lala01.jar
./lala01_lib/jogl-all.jar
./lala01_lib/jogl-all-natives-linux-amd64.jar
./lala01_lib/... etc ..

Test-2:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Package required libraries into generated JAR

Result: Works!

./lala02.jar:
Manifest-Version: 1.0
Rsrc-Class-Path: ./ gluegen-rt-natives-linux-amd64.jar gluegen-rt.jar
jogl-all-natives-linux-amd64.jar jogl-all.jar
Class-Path: .
Rsrc-Main-Class: Test01
Main-Class: org.eclipse.jdt.internal.jarinjarloader.JarRsrcLoader

JogAmp JAR File Handling

2015-10-31T20:55:53Z

Mraynsford: Add example assembly descriptor file

= Native JAR Files =

See [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFiles Native JAR Files] explained.

Native JAR files are loaded [{{SERVER}}/jogl/doc/userguide/index.html#automatednativelibraryloading automatically].

= Applet / JNLP Usage =

* [[Using JOGL in a Java applet|Using JOGL in a Java Applet]]
* [[Using JOGL in Java Web Start|Using JOGL in Java Web Start]]

A short ''copy'' is included in the static page [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NApplets JOGL Deployment using NApplet].

= Custom Bundling =

== Multi-Jar ==
[{{SERVER}}/bugzilla/show_bug.cgi?id=843 Multi-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

However, since we don't want to patronize our user base, we support this feature with our native JAR lib loading mechanism.

It is possible to merge all modules together, i.e.

multi.jar:
gluegen-rt.jar
jogl-all.jar
user-app.jar

multi-natives-<os.and.arch>.jar:
gluegen-rt-natives-<os.and.arch>.jar
jogl-all-natives-<os.and.arch>.jar

A combination with Fat-Jar is possible.

== Fat-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=845 Discouraged Fat-Jar]

This configuration is discouraged, since such deployment removes our artifacts as stored in
the jar's manifest file, which helps identifying the jogamp modules for bug reports etc.

Furthermore, adding all native library files for all supported platforms
will add-up to +3M of _compressed_ jar data!

However, since we don't want to patronize our user base,
we support this feature with our native JAR lib loading mechanism.

=== Usage ===

If the modules's jar file contains the folder 'natives/<os.and.arch>/'
we assume a fat-jar and attempt to load all native libraries from the same.

If we don't have a fat-jar or if fat-jar loading doesn't result in extracted native libraries,
we assume a regular slim jar file.

Layout:

/com/lala1/Lala1.class
/com/lala2/Lala2.class
/natives/<os.and.arch>/libLala1.so
/natives/<os.and.arch>/libLala2.so

A combination w/ Multi-Jar is of course possible.

=== Creation ===

==== Ant ====
You can use the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task] to create a fat JAR. You must avoid file names collision, i.e you must exclude the file(s) with the same name(s) in multiple JARs. You can use [https://ant.apache.org/manual/Tasks/manifest.html Ant manifest task] to create a manifest file. The following line just keeps the strict minimum to make JogAmp work and should be used with the [http://ant.apache.org/manual/Tasks/jar.html Ant jar task]:

<zipfileset src="jogamp-fat.jar" includes="**/*.class,**/*.png,**/*.glsl,**/*.vp,**/*.fp,**/*.bvp,**/*.bfp,**/*.so,**/*.jnilib,**/*.dylib,**/*.dll,**/.bin"/>

==== Maven ====
[http://maven.apache.org/plugins/maven-shade-plugin/index.html Maven Shade Plugin] is the recommended plugin to use to create fat JARs with [http://maven.apache.org Maven]. [http://maven.apache.org/plugins/maven-shade-plugin/examples/executable-jar.html This example] shows how to set some entries in the manifest file.

==== Maven Assembly Plugin ====

An example descriptor file that produces a fat jar containing all of the calling project's dependencies, and the JOGL/GlueGen native jar files placed into the correct directory inside the jar:

<pre>
<assembly
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">

<id>with-dependencies</id>
<includeBaseDirectory>false</includeBaseDirectory>

<formats>
<format>jar</format>
</formats>

<dependencySets>


<dependencySet>
<outputDirectory>/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<unpackOptions>
<excludes>
<exclude>libgluegen-rt*</exclude>
<exclude>libjogl_desktop.*</exclude>
<exclude>libjogl_mobile.*</exclude>
<exclude>libnativewindow_awt.*</exclude>
<exclude>libnativewindow_macosx.*</exclude>
<exclude>libnativewindow_x11.*</exclude>
<exclude>libnewt.*</exclude>
</excludes>
</unpackOptions>
</dependencySet>




<dependencySet>
<outputDirectory>/natives/linux-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/linux-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-linux-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-linux-i586</include>
</includes>
<unpackOptions>
<includes><include>*.so</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-amd64/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-amd64</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-amd64</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/windows-i586/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-windows-i586</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-windows-i586</include>
</includes>
<unpackOptions>
<includes><include>*.dll</include></includes>
</unpackOptions>
</dependencySet>

<dependencySet>
<outputDirectory>/natives/macosx-universal/</outputDirectory>
<useProjectArtifact>true</useProjectArtifact>
<scope>runtime</scope>
<unpack>true</unpack>
<includes>
<include>org.jogamp.gluegen:gluegen-rt:jar:natives-macosx-universal</include>
<include>org.jogamp.jogl:jogl-all:jar:natives-macosx-universal</include>
</includes>
<unpackOptions>
<includes><include>*.jnilib</include></includes>
</unpackOptions>
</dependencySet>
</dependencySets>
</assembly>
</pre>

This can be called in the usual manner (assuming that the descriptor file is in <tt>src/main/assembly/application.xml</tt>:

<pre>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<archive>
<manifest>
<mainClass>com.example.main.SomeMainClassHere</mainClass>
</manifest>
</archive>
<descriptors>
<descriptor>src/main/assembly/application.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</pre>

== One-Jar ==

[{{SERVER}}/bugzilla/show_bug.cgi?id=846 One-Jar]

One-Jar is incomplete, i.e. it does not provide a URL handler for
it's jar-in-jar resources - hence we would need to implement this functionality manually.

See [{{SERVER}}/bugzilla/show_bug.cgi?id=846#c1 One-Jar lacks of URLHandler ...]

For now, one can use Eclipse working jar-in-jar feature (see below).
Since Eclipse is under an open source license, one should be able
to locate the source code and include in a standalone toolkit, if so required.

== JarMatey ==

[http://staticvoidgames.com/JarMatey/ JarMatey] is an [https://github.com/KevinWorkman/JarMatey open source] tool for creating standalone self-executing JARs, similar to One-Jar but with a graphical user interface and no support for build tools (Ant, Maven). You can find a detailed tutorial about it [http://staticvoidgames.com/tutorials/deployment/joglExample here].

== Eclipse ==

Native JAR files and their respective base JAR files can be bundled in [{{SERVER}}/bugzilla/show_bug.cgi?id=522#c7 custom ways, e.g. eclipse Jar-In-Jar etc].

Manual tested w/ Eclipse:

Preparations:
===============

1) Set up a vanilla eclipse (3.7.0) workspace

2) Add the JOGL User Library:
- Window.Preference
- Java.Build_Path.User_Libraries:
+ JOGL
+ gluegen-rt.jar
+ jogl-all.jar
+ gluegen-rt-natives-linux-amd64.jar
+ jogl-all-natives-linux-amd64.jar

You may add all other native JARs here.
Note that these are not required in the CLASSPATH by JOGL,
however, they are required by Eclipse to export your project as a Runnable JAR File.

3) New test project
- Right-click your project in the Package Explorer and click "Properties".
- Select "Java Build Path" and click the "Libraries" tab.
+ JOGL
- Add some simple code ..
- Run as Java Application ..

Test-1:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Copy required libraries into a sub-folder next to the generated JAR

Result: Works!

./lala01.jar
./lala01_lib/jogl-all.jar
./lala01_lib/jogl-all-natives-linux-amd64.jar
./lala01_lib/... etc ..

Test-2:
=========

Export
- Right-click your project in the Package Explorer and click "Export"
- Select Java.Runnable_JAR_file
+ Launch configuration
+ some destination path
+ Library handling:
Package required libraries into generated JAR

Result: Works!

./lala02.jar:
Manifest-Version: 1.0
Rsrc-Class-Path: ./ gluegen-rt-natives-linux-amd64.jar gluegen-rt.jar
jogl-all-natives-linux-amd64.jar jogl-all.jar
Class-Path: .
Rsrc-Main-Class: Test01
Main-Class: org.eclipse.jdt.internal.jarinjarloader.JarRsrcLoader

Maven

2014-08-07T10:48:50Z

Mraynsford: /* Available packages */

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the package where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.joal
|joal-android
|2.2.0
|JOAL Android runtime
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl-android
|2.2.0
|JOCL Android runtime
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-android-main
|2.2.0
|Meta-package for automatic dependency resolution for JOGL (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|2.0.2
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|2.0.2
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|nativewindow-main
|2.2.0
|Native window drivers for NEWT (atomic frontend)
|-
|org.jogamp.jogl
|newt
|2.0.2
|NEWT code and native libraries (atomic jars)
|-
|org.jogamp.jogl
|newt-main
|2.2.0
|NEWT code and native libraries (atomic frontend)
|-
|org.jogamp.jogl
|occulusvr
|2.2.0
|JOGL code and native libraries (Oculus VR atomic jar files)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

= Android =

There is a [[Maven_And_Android|seperate page]] documenting one method of producing packages that work on both Android and ordinary
desktop Java.

SW Tracking Report Objectives for the release 2.1.5

2014-03-06T11:19:36Z

Mraynsford: Added 991

= Bugs =

List started on 2014-02-01, concluding [[SW Tracking Report Objectives for the release 2.1.4|Release 2.1.4]] - '''Open''' - continuation @ [[SW Tracking Report Objectives for the release 2.2.0|Release 2.2.0]].

This is a bugfix and enhancement release..

* [{{SERVER}}/bugzilla/buglist.cgi?chfield=bug_status&chfieldfrom=2014-02-01&chfieldto=2014-02-21&chfieldvalue=RESOLVED&classification=Unclassified&classification=JogAmp_Core&query_format=advanced&resolution=---&resolution=FIXED&resolution=INVALID&resolution=WONTFIX&resolution=DUPLICATE&resolution=WORKSFORME&resolution=MOVED&title=Bug%20List:%20Progress_2_1_5 Closed bugs 2.1.5] [{{SERVER}}/bugzilla/buglist.cgi?chfield=bug_status&chfieldfrom=2014-02-01&chfieldto=2014-02-21&chfieldvalue=RESOLVED&classification=Unclassified&classification=JogAmp_Core&query_format=advanced&resolution=---&resolution=FIXED&resolution=INVALID&resolution=WONTFIX&resolution=DUPLICATE&resolution=WORKSFORME&resolution=MOVED&title=Bug%20List:%20Progress_2_1_5&ctype=atom RSS Feed]

== Bugs already fixed for this release ==

{{#bugzilla:
|disablecache=1
|status=resolved,verified
|id=684,927,958,962,970,972,974,975,980,984,991
|columns=id,priority,status,severity,component,summary,votes
|sort=id
|order=desc
|noresultsmessage=Lazy devs}}

== JOCL Bugs already fixed for this release ===

{{#bugzilla:
|disablecache=1
|status=resolved,verified
|id=920,959,960,963,964,978,979,981
|columns=id,priority,status,severity,component,summary,votes
|sort=id
|order=desc
|noresultsmessage=Lazy devs}}

== Bugs to fix for this release w/ low effort (root causes clearly identified, reporter available) ==

{{#bugzilla:
|disablecache=1
|status=unconfirmed,in_progress,confirmed
|id=684,927,980,984
|columns=id,priority,status,severity,component,summary,votes
|sort=id
|order=desc
|noresultsmessage=We have no bugs quickly fixable to fix for this release}}

Maven

2013-07-22T18:21:54Z

Mraynsford:

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the package where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|2.0.2
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|2.0.2
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|newt
|2.0.2
|NEWT code and native libraries (atomic jars)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

= Android =

There is a [[Maven_And_Android|seperate page]] documenting one method of producing packages that work on both Android and ordinary
desktop Java.

Maven And Android

2013-07-22T18:20:01Z

Mraynsford: Note 2.0.2

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0.2</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0.2</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0.2</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>10</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0.2</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0.2</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

<pre>
$ adb install jp4da-android/target/jp4da-android.apk
1026 KB/s (2334537 bytes in 2.221s)
pkg: /data/local/tmp/jp4da-android.apk
Success
</pre>

The program running on an ordinary Linux desktop:

[[File:blue.png|Highly complex rendering]]

The program installed on the Android emulator:

[[File:maven-android-emu1.png|The installed application]]

The program running on the Android emulator:

[[File:maven-android-emu2.png|The running application]]

Maven

2013-07-22T18:18:22Z

Mraynsford: /* Package details */

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the package where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|2.0.2
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|2.0.2
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|newt
|2.0.2
|NEWT code and native libraries (atomic jars)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-22T18:17:38Z

Mraynsford: Note 2.0.2

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|2.0.2
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|2.0.2
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|newt
|2.0.2
|NEWT code and native libraries (atomic jars)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-11T16:29:51Z

Mraynsford: Add package table

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2-rc12</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Available packages =

{|
|Group ID
|Artifact ID
|Since
|Description
|-
|org.jogamp.gluegen
|gluegen-rt-android
|2.0.2-rc12
|GlueGen runtime code and native libraries (Android)
|-
|org.jogamp.gluegen
|gluegen-rt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for the GlueGen runtime
|-
|org.jogamp.gluegen
|gluegen-rt
|2.0-rc11
|GlueGen runtime code and native libraries
|-
|org.jogamp.gluegen
|gluegen
|2.0-rc11
|GlueGen non-runtime code and native libraries (and atomic jars)
|-
|org.jogamp.joal
|joal-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOAL
|-
|org.jogamp.joal
|joal
|2.0-rc11
|JOAL code and native libraries
|-
|org.jogamp.jocl
|jocl-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOCL
|-
|org.jogamp.jocl
|jocl
|2.0-rc11
|JOCL code and native libraries
|-
|org.jogamp.jogl
|jogl-all-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL
|-
|org.jogamp.jogl
|jogl-all
|2.0-rc11
|JOGL code and native libraries
|-
|org.jogamp.jogl
|jogl-android
|2.0.2-rc12
|JOGL code and native libraries (Android)
|-
|org.jogamp.jogl
|jogl-mobile-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (mobile)
|-
|org.jogamp.jogl
|jogl-mobile
|2.0-rc11
|JOGL mobile code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt-main
|2.0-rc11
|Meta-package for automatic dependency resolution for JOGL (without AWT)
|-
|org.jogamp.jogl
|jogl-noawt
|2.0-rc11
|JOGL code and native libraries (without AWT)
|-
|org.jogamp.jogl
|jogl
|
|JOGL atomic jar files
|-
|org.jogamp.jogl
|nativewindow
|
|Native window drivers for NEWT (atomic jars)
|-
|org.jogamp.jogl
|newt
|
|NEWT code and native libraries (atomic jars)
|-
|}

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-11T15:52:12Z

Mraynsford: Note portability

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2-rc12</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available. It's <i>not</i> recommended to depend on platform-specific jar files
in the manner shown above unless there's an extremely good reason to do so; to do otherwise
harms portability for no good reason!

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-11T13:08:23Z

Mraynsford: /* The jogamp.org test repository (optional) */

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2-rc12</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available.

= The jogamp.org test repository (optional) =

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-11T13:08:09Z

Mraynsford: Headers

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

= Add dependencies on the correct packages =

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2-rc12</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= Package details =

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

= Atomic jar files (optional) =

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available.

=== The jogamp.org test repository (optional) ===

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Setting up a JogAmp project in your favorite IDE

2013-07-11T12:46:11Z

Mraynsford: /* Maven */

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

See [[JogAmp JAR File Handling|JogAmp JAR File Handling]], for details on native JAR files and custom JAR bundling.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Add gluegen-rt.jar and jogl.jar to the project.
You may add all other gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar JARs as well.
Note that these are not required in the CLASSPATH by JOGL,
however, they are required by Eclipse to export your project as a Runnable JAR File.
* Expand the jogl-all and gluegen-rt JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl-all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Since <tt>2.0-rc11</tt>, packages for all the JogAmp projects have been pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central]. Please see the
[[Maven]] page for details on how to use them in your projects.

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Maven

2013-07-11T12:44:28Z

Mraynsford: Add atomic example

__TOC__

JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogamp Maven Central].

=== Add dependencies on the correct packages ===

If you don't know which packages you want, you almost certainly want to use the
<tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> packages, as these automatically
set up the correct dependencies on the native jar files for all platforms.

As an example, if your project uses JOGL <tt>2.0.2-rc12</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

Additionally, for <tt>joal</tt> and <tt>jocl</tt> support:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.jocl</groupId>
<artifactId>jocl-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.joal</groupId>
<artifactId>joal-main</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</dependencies>
</code>

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

=== Package details ===

For each JogAmp project, there are essentially two packages published: One contains the main compiled
jar files and any associated native library jar files, and the other simply contains <i>dependencies</i>
on those files. Using <tt>jogl-all</tt> and <tt>jogl-all-main</tt> as the example, the <tt>jogl-all</tt>
package in the jogamp.org test repository:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all/2.0.2-rc12/

Note that there are many native jar files attached to the main package. However, if you were to use
the following dependency in your own project:

<code>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0.2-rc12</version>
</dependency>
</code>

Maven would download <tt>jogl-all-2.0.2-rc12.jar</tt> but would completely ignore all of the other
native jar files. Why? The reason for this is that the native jar files are uploaded as extra artifacts
to the <tt>jogl-all</tt> package and are, in a manner of speaking, not really considered to be part of
the project where dependencies are concerned. The POM for the <tt>jogl-all-main</tt> package adds
explicit dependencies on all of the extra artifacts in the <tt>jogl-all</tt> package:

http://jogamp.org/deployment/maven/org/jogamp/jogl/jogl-all-main/2.0.2-rc12/jogl-all-main-2.0.2-rc12.pom

So, when you add a dependency on <tt>jogl-all-main</tt> in your own project, the native jar files of
<tt>jogl-all</tt> are brought in as transitive dependencies and everything works as expected.

=== Atomic jar files (optional) ===

The so-called <i>atomic</i> jar files are provided as attachments to the <tt>jogl</tt>, <tt>newt</tt>,
<tt>nativewindow</tt> and <tt>gluegen</tt> packages. As an example, to depend only on the Linux AMD64
native jar files, on X11, using only the core of <tt>jogl</tt> and the native window toolkit in your
own projects, use the following dependencies:

<code>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
</dependency>
<dependency>
<groupId>org.jogamp.gluegen-rt</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl</artifactId>
<version>2.0.2-rc12</version>
<classifier>os-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>newt</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>core</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>natives-linux-amd64</classifier>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>nativewindow</artifactId>
<version>2.0.2-rc12</version>
<classifier>driver-x11</classifier>
</dependency>
</code>

Note that the choice of which atomic jars are required is really outside of the scope of this
documentation. It's recommended that you browse the packages in question to see which jar
files are available.

=== The jogamp.org test repository (optional) ===

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

Maven

2013-07-11T12:35:25Z

Mraynsford: Fix code element

Maven

2013-07-11T12:35:04Z

Mraynsford: Document *-main packages

Maven

2013-07-11T12:23:10Z

Mraynsford: /* Add dependencies on the correct packages */

Maven

2013-07-11T12:21:12Z

Mraynsford: Created page with '__TOC__ JogAmp now contains support for Maven. As of <tt>2.0-rc11</tt>, packages are pushed to [http://search.maven.org/#search|ga|1|jogamp Maven Central]. === Add dependencie…'

Downloading and installing JOGL

2013-04-04T16:43:12Z

Mraynsford: Maven

Before you can build a project that uses JOGL [https://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE in your IDE or on the command line], you'll need to download and install the JOGL JAR files and native JARs or native library files (<tt>.dll</tt>/<tt>.so</tt>/<tt>.jnilib</tt> files).

You have a choice of JOGL versions to download. The [{{SERVER}}/deployment/jogamp-current/archive/ latest stable version] is the safest, but lags behind in features. The [{{SERVER}}/deployment/autobuilds/master/ latest automatic build] contains all checked-in code, but may be failing some tests.

= Downloading the latest stable version =

Go to [{{SERVER}}/deployment/jogamp-current/archive/ this page] and download the all-in-one 7z archive file:

: [{{SERVER}}/deployment/jogamp-current/archive/jogamp-all-platforms.7z jogamp-all-platforms.7z]

== Using the 7z jogamp-all-platforms archive ==

After inflating the file with [http://www.7-zip.org/ 7zip], you will have the general directory structure:

<pre>
<jogamp-all-platforms>/
<jogamp-all-platforms>/etc/test.sh
<jogamp-all-platforms>/etc/test.bat
<jogamp-all-platforms>/etc/test_dbg.sh
<jogamp-all-platforms>/etc/test_dbg.bat
<jogamp-all-platforms>/jar/<module>.jar
<jogamp-all-platforms>/jar/<module>-natives-<os.and.arch>.jar
<jogamp-all-platforms>/lib/
<jogamp-all-platforms>/<module>-java-src.zip*
</pre>
Legend:
* [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFileNameConvention os.and.arch]
* module: gluegen, joal, jogl or jocl

Now you can '''test''' the ''archive'' as described
in [[Jogamp Versioning and Releases#Runtime Version Check|runtime version check]]
and [[Jogamp Versioning and Releases#Runtime Debug Logs|runtime debug test]].

If anything doesn't work as predicted, please follow our [[Jogl FAQ#Bugreports & Testing|bugreport guide]].

While keeping the above directory structure as-is, you can go ahead and
* add the non-native JAR files to your CLASSPATH (IDE, manual, ..)
* attach the java-source files to the non-native JAR files (IDE)

.. now you are set to start using JogAmp module in your project.

The above is detailed in [[Setting_up_a_JogAmp_project_in_your_favorite_IDE#Eclipse_IDE_project|Eclipse Project]]
and [[Setting_up_a_JogAmp_project_in_your_favorite_IDE#Eclipse_IDE_user_library|Eclipse User Library]].

= Downloading the latest aggregated autobuild =

Got to [{{SERVER}}/deployment/archive/master/?C=M;O=D this page] and navigate into the first folder,
which shall be the latest ''aggregated autobuild''.

Then navigate further down to '''archive''' and download the file '''jogamp-all-platforms.7z'''.

For example, on '''13-Mar-2013 20:19 CET''', the latest ''aggregated autobuild'' was:

[{{SERVER}}/deployment/archive/master/gluegen_646-joal_408-jogl_930-jocl_756/archive/jogamp-all-platforms.7z {{SERVER}}/deployment/archive/master/gluegen_646-joal_408-jogl_930-jocl_756/archive/jogamp-all-platforms.7z]

Now you can continue [[#Using the 7z jogamp-all-platforms archive|here]].

= Downloading the latest automatic build =

For the latest automatic build, we have to download gluegen and jogl separately.

First, go to [{{SERVER}}/deployment/autobuilds/master/?C=M;O=D this page] and click on the most recent <tt>gluegen-b*</tt> directory. Then download one of these files for each platform you're developing on:

: 32-bit Windows: <tt>gluegen-2.0-bvvv-20yymmdd-windows-i586.7z</tt>
: 64-bit Windows: <tt>gluegen-2.0-bvvv-20yymmdd-windows-amd64.7z</tt>
: 32/64-bit Mac OS X: <tt>gluegen-2.0-bvvv-20yymmdd-macosx-universal.7z</tt>
: 32-bit Linux: <tt>gluegen-2.0-bvvv-20yymmdd-linux-i586.7z</tt>
: 64-bit Linux: <tt>gluegen-2.0-bvvv-20yymmdd-linux-amd64.7z</tt>
: 32-bit Solaris: <tt>gluegen-2.0-bvvv-20yymmdd-solaris-i586.7z</tt>
: 64-bit Solaris: <tt>gluegen-2.0-bvvv-20yymmdd-solaris-amd64.7z</tt>

Then, go back to [{{SERVER}}/deployment/autobuilds/master/?C=M;O=D this page] and click on the most recent <tt>jogl-b*</tt> directory. Then download one of these files for each platform you're developing on:

: 32-bit Windows: <tt>jogl-2.0-bvvv-20yymmdd-windows-i586.7z</tt>
: 64-bit Windows: <tt>jogl-2.0-bvvv-20yymmdd-windows-amd64.7z</tt>
: 32/64-bit Mac OS X: <tt>jogl-2.0-bvvv-20yymmdd-macosx-universal.7z</tt>
: 32-bit Linux: <tt>jogl-2.0-bvvv-20yymmdd-linux-i586.7z</tt>
: 64-bit Linux: <tt>jogl-2.0-bvvv-20yymmdd-linux-amd64.7z</tt>
: 32-bit Solaris: <tt>jogl-2.0-bvvv-20yymmdd-solaris-i586.7z</tt>
: 64-bit Solaris: <tt>jogl-2.0-bvvv-20yymmdd-solaris-amd64.7z</tt>

Note that these automatic builds may not have passed all the regression tests. You can check the test results on the [https://jogamp.org/chuck/ build server] to make sure you're not downloading a broken build.

== Native JARs vs. native library files ==

JOGL uses native libraries to interface with each platform's OpenGL library. You can either download these native libraries wrapped up in JAR files (the "native JARs" option), or you can download them as separate <tt>.dll</tt>/<tt>.so</tt>/<tt>.jnilib</tt> files (the "native library files" option).

When using native JARs, JOGL automatically unzips the native JARs at startup into a temporary directory, then loads the resulting <tt>.dll</tt>/<tt>.so</tt>/<tt>.jnilib</tt> files from there. When using native library files, JOGL just loads them directly from where they sit, with no unzipping.

Using native JARs is usually easiest, since there are fewer files to manage and it allows different platforms' native library files to coexist in the same directory. Only use the native library files directly if you need fine control over native library file placement or if your app doesn't have permissions to create temporary directories.

== Unzipping the files ==

Unzip all the downloaded files with [http://www.7-zip.org/ 7zip]. An unzipped file has this general directory structure:

<pre>
<archive>/
<archive>/jar/
<archive>/lib/
<archive>/<module>-java-src.zip*
</pre>

Now you may copy the required JARs out of each <tt>jar</tt> folder and the native library files (if you're using them) out of each <tt>lib</tt> folder. For a full desktop installation using native JARs, here are the files you need. Note that the native JAR names are different for each platform, so you can use some or all of the native JARs together to create a multi-platform installation.

{|cellpadding="4" cellspacing="0"
!align="left"|64-bit Windows
!align="left"|64-bit Linux
!align="left"|32/64-bit Mac
|-
|<tt>gluegen-rt.jar</tt>||<tt>gluegen-rt.jar</tt>||<tt>gluegen-rt.jar</tt>
|-
|<tt>jogl-all.jar</tt>||<tt>jogl-all.jar</tt>||<tt>jogl-all.jar</tt>
|-
|<tt>gluegen-java-src.zip</tt>||<tt>gluegen-java-src.zip</tt>||<tt>gluegen-java-src.zip</tt>
|-
|<tt>jogl-java-src.zip</tt>||<tt>jogl-java-src.zip</tt>||<tt>jogl-java-src.zip</tt>
|-
|<tt>gluegen-rt-natives-windows-amd64.jar</tt>||<tt>gluegen-rt-natives-linux-amd64.jar</tt>||<tt>gluegen-rt-natives-macosx-universal.jar</tt>
|-
|<tt>jogl-all-natives-windows-amd64.jar</tt>||<tt>jogl-all-natives-linux-amd64.jar</tt>||<tt>jogl-all-natives-macosx-universal.jar</tt>
|}
<br/>
{|cellpadding="4" cellspacing="0"
!align="left"|32-bit Windows
!align="left"|32-bit Linux
|-
|<tt>gluegen-rt.jar</tt>||<tt>gluegen-rt.jar</tt>
|-
|<tt>jogl-all.jar</tt>||<tt>jogl-all.jar</tt>||
|-
|<tt>gluegen-java-src.zip</tt>||<tt>gluegen-java-src.zip</tt>||
|-
|<tt>jogl-java-src.zip</tt>||<tt>jogl-java-src.zip</tt>||
|-
|<tt>gluegen-rt-natives-windows-i586.jar</tt>||<tt>gluegen-rt-natives-linux-i586.jar</tt>
|-
|<tt>jogl-all-natives-windows-i586.jar</tt>||<tt>jogl-all-natives-linux-i586.jar</tt>
|}

<br/>
For a full desktop installation using native library files, here are the files you need. Note that the native library files have the same names for 32-bit and 64-bit platforms, so 32-bit and 64-bit platforms can't coexist in one installation.
<br/>

{|cellpadding="4" cellspacing="0"
!align="left"|Windows
!align="left"|Linux
!align="left"|Mac
|-
|<tt>gluegen-rt.jar</tt>||<tt>gluegen-rt.jar</tt>||<tt>gluegen-rt.jar</tt>
|-
|<tt>jogl-all.jar</tt>||<tt>jogl-all.jar</tt>||<tt>jogl-all.jar</tt>
|-
|<tt>gluegen-java-src.zip</tt>||<tt>gluegen-java-src.zip</tt>||<tt>gluegen-java-src.zip</tt>
|-
|<tt>jogl-java-src.zip</tt>||<tt>jogl-java-src.zip</tt>||<tt>jogl-java-src.zip</tt>
|-
|<tt>gluegen-rt.dll</tt>||<tt>libgluegen-rt.so</tt>||<tt>libgluegen-rt.jnilib</tt>
|-
|<tt>jogl_desktop.dll</tt>||<tt>libjogl_desktop.so</tt>||<tt>libjogl_desktop.jnilib</tt>
|-
|<tt>nativewindow_awt.dll</tt>||<tt>libnativewindow_awt.so</tt>||<tt>libnativewindow_awt.jnilib</tt>
|-
|<tt>nativewindow_win32.dll</tt>||<tt>libnativewindow_x11.so</tt>||<tt>libnativewindow_macosx.jnilib</tt>
|-
|<tt>newt.dll</tt>||<tt>libnewt.so</tt>||<tt>libnewt.jnilib</tt>
|}

= Maven =
Alternatively, the Jogamp packages are available through Maven.

See the [[Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven|maven instructions]] for a guide to using Jogamp in
Maven projects.

= More information =

JogAmp follows a [[Jogamp_Versioning_and_Releases#Release_Classification|release scheme]],
which describes the following locations to download the 7z archives from:

* [{{SERVER}}/deployment/ Deployment Home]
** [{{SERVER}}/deployment/jogamp-current/archive/ Signed Release]
** [{{SERVER}}/deployment/jogamp-next/archive/ Signed Candidate]
** [{{SERVER}}/deployment/jogamp-next/v2.0-rc3archive/ Specific Version]

[{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html JOGL Deployment] describes the content of the 7z archive files.

These installations contain all of JOGL. If you want to remove parts you don't use, see [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html JOGL Deployment] for more information.

Jogamp Versioning and Releases

2013-04-04T16:40:30Z

Mraynsford:

__TOC__

== Releases ==

[[Release 2.0-rc11|2.0-rc11]],[[Release 2.0-rc10|2.0-rc10]], [[Release 2.0-rc9|2.0-rc9]], [[Release 2.0-rc8|2.0-rc8]], [[Release 2.0-rc7|2.0-rc7]], [[Release 2.0-rc6|2.0-rc6]], [[Release 2.0-rc5|2.0-rc5]], [[Release 2.0-rc4|2.0-rc4]], [[Release 2.0-rc3|2.0-rc3]], [[Release 2.0-rc2|2.0-rc2]], [[Release 2.0-rc1|2.0-rc1]]

=== Current Aliases ===

* [http://jogamp.org/deployment/jogamp-current/ jogamp-current] -> [http://jogamp.org/deployment/v2.0-rc11/ v2.0-rc11]
* [http://jogamp.org/deployment/jogamp-next/ jogamp-next] -> [http://jogamp.org/deployment/v2.0-rc11/ v2.0-rc11]
* [http://jogamp.org/deployment/webstart/ webstart] -> [http://jogamp.org/deployment/v2.0-rc11/ v2.0-rc11]
* [http://jogamp.org/deployment/webstart-next/ webstart-next] -> [http://jogamp.org/deployment/v2.0-rc11/ v2.0-rc11]

== Release Classification ==

Releases follow the above mentioned [[#Version_Classification|versioning]] scheme.

The following list is ordered from <i>stable and oldest</i> to <i>experimental and newest</i>.

=== [{{SERVER}}/deployment/jogamp-current/ Signed Release] ===
* This is our current signed release, IE a manual promoted and signed autobuild.
* It is suitable for JNLP and Applets (with or without JNLP).
* This is the <b>most stable and recommended</b> version.
* [{{SERVER}}/deployment/jogamp-current/archive/ Archive folder] containing [[#Release_and_Archived_Files|platform ZIP files]] for manual installation.
* [[Downloading and installing JOGL#Downloading the latest aggregated autobuild|this section]]
* See instructions for [[Downloading and installing JOGL#Downloading the latest stable version|downloading and installing]].

=== [{{SERVER}}/deployment/jogamp-next/ Signed Release Candidate] ===
* This is our signed release candidate, IE a manual promoted and signed autobuild.
* It is suitable for JNLP and Applets (with or without JNLP).
* [{{SERVER}}/deployment/jogamp-next/archive/ Platform ZIP archive's URL] for manual installation.
* [{{SERVER}}/deployment/jogamp-next/archive/ Archive folder] containing [[#Release_and_Archived_Files|platform ZIP files]] for manual installation.
* See instructions for [[Downloading and installing JOGL#Downloading the latest stable version|downloading and installing]].

=== [{{SERVER}}/deployment/v2.0-rc3/ Signed Release Specific Version] ===
* This is a specific signed release, IE a manual promoted autobuild.
* It is suitable for JNLP and Applets (with or without JNLP).
* [{{SERVER}}/deployment/v2.0-rc3/archive/ Archive folder] containing [[#Release_and_Archived_Files|platform ZIP files]] for manual installation.
* See instructions for [[Downloading and installing JOGL#Downloading the latest stable version|downloading and installing]].

=== [{{SERVER}}/deployment/archive/master/?C=M;O=D Latest Aggregated Autobuild] ===
* This is our latest aggregated autobuild, which we seem fit for broad testing and submitting a [[Jogl FAQ#Bugreports & Testing|bugreport]].
* It is not signed and hence not suitable for JNLP and Applets.
* See instructions for [[Downloading and installing JOGL#Downloading the latest aggregated autobuild|downloading and installing]].

=== [{{SERVER}}/deployment/autobuilds/ Autobuilds] ===
What others call <i>nightlies</i>, we call it autobuild.
Autobuilds are provided by our [{{SERVER}}/chuck/job/jogl/ Jenkins build server]:
* For [{{SERVER}}/chuck/job/jogl/ each project build reports] are available:
** [{{SERVER}}/chuck/job/jogl/lastSuccessfulBuild/ Last Successful JOGL Build]
** [{{SERVER}}/chuck/job/jogl/476/ JOGL Build 476]
* They are [{{SERVER}}/chuck/job/jogl/476/changes#detail0 triggered by git commits]
* Here is a [{{SERVER}}/chuck/job/jogl/changes list of all JOGL changes].
* These builds are also tested on all supported platforms automatically with junit, see a [{{SERVER}}/chuck/job/jogl/label=win7-x86_64-nvida/lastCompletedBuild/testReport/ complete test report from one platform].
* [{{SERVER}}/deployment/autobuilds/master/jogl-b485-2011-09-20_08-30-36/ Autobuild URL] containing [[#Autobuild_Files|platform ZIP files]] for manual installation.

=== [{{SERVER}}/deployment/archive/ Archived builds] ===
* Contains archived builds and releases.
* May be signed.
* [{{SERVER}}/deployment/archive/rc/gluegen_28-joal_17-jogl_41-jocl_25/archive/ archive URL] containing [[#Release_and_Archived_Files|platform ZIP files]] for manual installation.

== Version Classification ==

=== Version Fingerprint ===

You can get the [[Jogl FAQ#Get the Source Code|get the source code]] via git,
hence all references of a JogAmp module version boils down to:

* module base version
* git commit sha1 hash
* build number
* module OS and ARCH

We construct a full version string as follows:
<pre>
<module>-<base_version>-b<build_number>-<yyyymmdd>
</pre>

=== artifact.properties ===

The version fingerprint is available in the
[{{SERVER}}/deployment/autobuilds/master/jogl-b485-2011-09-20_08-30-36/artifact.properties artifact.properties] file:
<pre>
gluegen.build.number=200
gluegen.build.id=2010-11-09_22-30-24
gluegen.build.branch=master
gluegen.build.commit=92e1e8b24d128e08f13b05bd630ad7b0bf1cbf9f
jogl.build.number=209
jogl.build.id=2010-11-09_22-35-00
jogl.build.branch=master
jogl.build.commit=4ea473a2cbf59fcbd8e82d26da389cd8c2b4a291
</pre>

We deploy artifacts.properties in the online [{{SERVER}}/deployment/autobuilds/master/jogl-b485-2011-09-20_08-30-36/ build folder]
and within the platform ZIP archives.

=== JAR Manifest ===

The version fingerprint is also included within each JAR Manifest file,
where the Specification-Version equals the module base version
and the Implementation-Version equals the above mentioned full version string
<pre>
Manifest-Version: 1.0
Ant-Version: Apache Ant 1.8.0
Created-By: 1.6.0_21-b06 (Sun Microsystems Inc.)
Specification-Title: Java Bindings for OpenGL API Specification
Specification-Version: 2.0
Specification-Vendor: JogAmp community
Implementation-Title: Java Bindings for OpenGL Runtime Environment
Implementation-Version: 2.0-b209-20101110
Implementation-Branch: master
Implementation-Commit: 4ea473a2cbf59fcbd8e82d26da389cd8c2b4a291
Implementation-Vendor: JogAmp community
Extension-Name: javax.media.opengl
Implementation-Vendor-Id: com.jogamp
Trusted-Library: true
</pre>

Each module has also a base version, like major and minor, ie 2.0,
which we may change to emphasize major feature and API changes.

==== Runtime Version Check ====

Each module has a build in [http://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/com/jogamp/common/util/JogampVersion.html JogampVersion] specialization with a static <code>getInstance()</code> method to access the singleton instance,
eg. for the [http://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/com/jogamp/common/GlueGenVersion.html#getInstance%28%29 GlueGenVersion] or [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/JoglVersion.html#getInstance%28%29 JoglVersion]. You may utilize the version information from within your application in a programmatic manner. For the latter you may find the [http://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/com/jogamp/common/os/Platform.html Platform] information useful as well.

Each module's [http://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/com/jogamp/common/util/JogampVersion.html JogampVersion] specialization also contain a static main entry allowing you to retrieve the version information at runtime as described below.

When invoked, ie via JOGL's platform ZIP file:
* sh etc/test.sh (Unixoid), or
* etc\test.bat (Windows)
you will see the full dump of the runtime platform and the above mentioned version footprint.

<pre>
-----------------------------------------------------------------------------------------------------
Platform: LINUX / Linux 3.7.1-x64-k10-nlb-jau01 (os), amd64 (arch), GENERIC_ABI, 8 cores
MachineDescription: runtimeValidated true, littleEndian true, 32Bit false, primitive size / alignment:
int8 1 / 1, int16 2 / 2
int 4 / 4, long 8 / 8
int32 4 / 4, int64 8 / 8
float 4 / 4, double 8 / 8, ldouble 16 / 16
pointer 8 / 8, page 4096
Platform: Java Version: 1.6.0_38, VM: Java HotSpot(TM) 64-Bit Server VM, Runtime: Java(TM) SE Runtime Environment
Platform: Java Vendor: Sun Microsystems Inc., http://java.sun.com/, JavaSE: true, Java6: true, AWT enabled: true
-----------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------
Package: com.jogamp.common
Extension Name: com.jogamp.common
Specification Title: GlueGen Java Bindings Generator
Specification Vendor: JogAmp Community
Specification Version: 2.0
Implementation Title: GlueGen Run-Time
Implementation Vendor: JogAmp Community
Implementation Vendor ID: com.jogamp
Implementation URL: http://jogamp.org/
Implementation Version: 2.0-b646-20130313
Implementation Branch: master
Implementation Commit: 1a4514accc8f61ab7ff5fe8c82d22a5ef356c865
-----------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------
Package: javax.media.opengl
Extension Name: javax.media.opengl
Specification Title: Java Bindings for OpenGL API Specification
Specification Vendor: JogAmp Community
Specification Version: 2.0
Implementation Title: Java Bindings for OpenGL Runtime Environment
Implementation Vendor: JogAmp Community
Implementation Vendor ID: com.jogamp
Implementation URL: http://jogamp.org/
Implementation Version: 2.0-b930-20130313
Implementation Branch: master
Implementation Commit: 58f6f4e5665ae2c72ec6bbd86ad5a36bef00de07
-----------------------------------------------------------------------------------------------------
Default Profiles on device X11GraphicsDevice[type .x11, connection :0, unitID 0, handle 0x0, owner false, ResourceToolkitLock[obj 0x4430d82d, isOwner false, <62c09554, 518bf072>[count 0, qsz 0, owner <NULL>]]]
Native
GL4bc true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL4 true [4.2 (Core profile, arb, ES2 compatible, FBO, hardware)]
GL3bc true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL3 true [4.2 (Core profile, arb, ES2 compatible, FBO, hardware)]
GL2 true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL2ES1 true
GLES1 true [1.0 (ES profile, FBO, software)]
GL2ES2 true
GLES2 true [2.0 (ES profile, ES2 compatible, FBO, software)]
Profiles
GLProfile[GL2ES2/GL4bc.hw]
GLProfile[GL2ES1/GL4bc.hw]
GLProfile[GL2/GL2.hw]
GLProfile[GL4/GL4.hw]
GLProfile[GL3/GL3.hw]
GLProfile[GL4bc/GL4bc.hw]
GLProfile[GL4bc/GL4bc.hw]
GLProfile[GLES2/GLES2.sw]
GLProfile[GLES1/GLES1.sw]
GLProfile[GL2GL3/GL4bc.hw]
GLProfile[GL3bc/GL3bc.hw]
default GLProfile[GL4bc/GL4bc.hw]

Desktop Capabilities:
GLCaps[glx vid 0x21, fbc 0x105: rgba 0x8/8/8/0, opaque, accum-rgba 16/16/16/16, dp/st/ms: 24/8/0, dbl, mono , hw, GLProfile[GL4bc/GL4bc.hw], on-scr[fbo, pbuffer [r2t 0, r2tr 0, float 0], bitmap]]
GLCaps[glx vid 0x22, fbc 0x106: rgba 0x8/8/8/0, opaque, accum-rgba 16/16/16/16, dp/st/ms: 24/8/0, dbl, mono , hw, GLProfile[GL4bc/GL4bc.hw], on-scr[fbo, pbuffer [r2t 0, r2tr 0, float 0], bitmap]]
...
EGL Capabilities:
GLCaps[egl cfg 0x19, vid 0x21: rgba 0x8/8/8/0, opaque, accum-rgba 0/0/0/0, dp/st/ms: 0/0/0, dbl, mono , sw, GLProfile[GLES2/GLES2.sw], on-scr[fbo, pbuffer [r2t 0, r2tr 0, float 0], bitmap], [0xd: GL, GLES1, GLES2, VG]]
GLCaps[egl cfg 0x1a, vid 0x21: rgba 0x8/8/8/0, opaque, accum-rgba 0/0/0/0, dp/st/ms: 0/0/0, dbl, mono , sw, GLProfile[GLES2/GLES2.sw], on-scr[fbo, pbuffer [r2t 0, r2tr 0, float 0], bitmap], [0xd: GL, GLES1, GLES2, VG]]
...
-----------------------------------------------------------------------------------------------------
X11GraphicsDevice[type .x11, connection :0]:
Native
GL4bc true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL4 true [4.2 (Core profile, arb, ES2 compatible, FBO, hardware)]
GL3bc true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL3 true [4.2 (Core profile, arb, ES2 compatible, FBO, hardware)]
GL2 true [4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware)]
GL2ES1 true
GLES1 true [1.0 (ES profile, FBO, software)]
GL2ES2 true
GLES2 true [2.0 (ES profile, ES2 compatible, FBO, software)]
Profiles
GLProfile[GL2ES2/GL4bc.hw]
GLProfile[GL2ES1/GL4bc.hw]
GLProfile[GL2/GL2.hw]
GLProfile[GL4/GL4.hw]
GLProfile[GL3/GL3.hw]
GLProfile[GL4bc/GL4bc.hw]
GLProfile[GL4bc/GL4bc.hw]
GLProfile[GLES2/GLES2.sw]
GLProfile[GLES1/GLES1.sw]
GLProfile[GL2GL3/GL4bc.hw]
GLProfile[GL3bc/GL3bc.hw]
default GLProfile[GL4bc/GL4bc.hw]

Swap Interval -1
GL Profile GLProfile[GL4bc/GL4bc.hw]
CTX VERSION 4.2 (Compatibility profile, arb, ES2 compatible, FBO, hardware) - 4.2.0 NVIDIA 310.32
GL jogamp.opengl.gl4.GL4bcImpl@6f9bb25a
GL_VENDOR NVIDIA Corporation
GL_RENDERER GeForce GTX 660/PCIe/SSE2
GL_VERSION 4.2.0 NVIDIA 310.32
GLSL true, has-compiler: true, version: 4.20 NVIDIA via Cg compiler
GL_EXTENSIONS 302
GL_ARB_arrays_of_arrays GL_ARB_base_instance ...
GLX_EXTENSIONS 27
GLX_ARB_fbconfig_float GLX_ARB_create_context_robustness ...
-----------------------------------------------------------------------------------------------------
Requested: GLCaps[rgba 0x8/8/8/0, opaque, accum-rgba 0/0/0/0, dp/st/ms: 16/0/0, dbl, mono , hw, GLProfile[GL4bc/GL4bc.hw], on-scr[.]]
Chosen : GLCaps[glx vid 0x27, fbc 0x10d: rgba 0x8/8/8/0, opaque, accum-rgba 16/16/16/16, dp/st/ms: 24/0/0, dbl, mono , hw, GLProfile[GL4bc/GL4bc.hw], on-scr[.]]
</pre>
The dump is hold in the file <pre>test.log</pre> which you should send to us in case of a bugreport.

===== Runtime Debug Logs =====

You may also like to send us the debug version:
* sh etc/test_dbg.sh (Unixoid), or
* etc\test_dbg.bat (Windows)
which produces the file <pre>test_dbg.log</pre> and should be send to us to complete the bugreport as well.

==== Retrieve Release Version Tag from GIT Hash ====

git-show-tags-of-commit.sh
<pre>
#! /bin/sh

sha1=$1
shift

git show-ref --tags -d | grep ^$sha1 | sed -e 's,.* refs/tags/,,' -e 's/\^{}//'
</pre>

JOGL example:
<pre>
> git-show-tags-of-commit.sh 9ff0b0dafea2a03a915c97eb1513c39c27b6a7ae
v2.0-rc8
</pre>

GlueGen example:
<pre>
> git-show-tags-of-commit.sh 4ce601b38ca8418eddbe8cca4d531e6161fae26b
v2.0-rc7
v2.0-rc8
</pre>

== Maven ==
See the [[Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven|maven instructions]] for a guide to using Jogamp in
Maven projects.

== Autobuild Files ==
[{{SERVER}}/deployment/autobuilds/master/jogl-b485-2011-09-20_08-30-36/ Autobuild Platform ZIP files] for each module
follow the [[#Version_Classification|versioning]] scheme plus contain the platform identifier [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFileNameConvention OS and ARCH]:
<pre>
jogl-2.0-b210-20101110-linux-amd64.zip
</pre>

== Release and Archived Files ==
The [{{SERVER}}/deployment/jogamp-current/archive/ release archive folder]
contains 7z archive files for each platform containing all modules, ie. ''jogamp-linux-'''os.and.arch'''.7z''.
The '''os.and.arch''' refers to the
[{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NativeJARFileNameConvention native file naming convention].

For example:
* <tt>jogamp-linux-amd64.7z</tt>
* <tt>jogamp-linux-i586.7z</tt>
* <tt>jogamp-windows-amd64.7z</tt>
* <tt>jogamp-windows-i586.7z</tt>

The folder also contains the Java API document ZIP files:
* <tt>gluegen-javadoc.zip</tt>
* <tt>jogl-javadoc.zip</tt>
* <tt>jocl-javadoc.zip</tt>
* <tt>joal-javadoc.zip</tt>

Maintainer and Contacts

2013-01-16T16:29:40Z

Mraynsford: /* Contacts */

= Maintainer =

* JogAmp IT Infrastructure, Architecture and Janitor
** [[#Sven Gothel|Sven Gothel]]
* Gluegen
** [[#Sven Gothel|Sven Gothel]]
* JOAL
** [[#Xerxes Rånby|Xerxes Rånby]]
* JOGL
** [[#Sven Gothel|Sven Gothel]]
** GPU Curve Rendering
*** [[#Rami Santina|Rami Santina]]
* Java3D
** [[#Harvey Harrison|Harvey Harrison]]
* JOCL
** [[#Sven Gothel|Sven Gothel]] ''(interim)''
* Engine Support
** [[#Julien Gouesse|Julien Gouesse]]
* Maven packages
** [[#Mark Raynsford|Mark Raynsford]]
* Art (graphics, demos, ..)
** [[#Dominik Ströhlein|Dominik Ströhlein]]
* ''Open Positions''
** JOCL
** jogl-utils

= Contacts =

You can address the JogAmp Community via:
* [http://jogamp.org/ Web]
* [http://forum.jogamp.org/ Forum/Mailinglist]
* [http://jogamp.org/wiki/index.php/Chatroom JogAmp IRC]
* Email
** mediastream [@] jogamp.org

<div id="Contact_Maintainer">
Please feel welcome to contact the maintainers for commercial support inquiries,
specific questions you seem not fit for public discussions or to fund the work.
</div>

== Sven Gothel ==
* sgothel [@] jausoft.com
* http://jausoft.com/blog/tag/jogl/
* Contracting and funding
** via ''Göthel Software e.K., contact jogamp [@] jausoft.com''
** micro payments [http://flattr.com/thing/1028522/JogAmp-Maintainer-Sven-Gothel via Flattr]

== Julien Gouesse ==
* gouessej [@] orange.fr
* http://gouessej.wordpress.com/tag/jogl/

== Xerxes Rånby ==
* xerxes [@] gudinna.com
* http://labb.zafena.se/?category_name=jogamp
* http://twitter.com/xranby
** Micro payments via flatter: http://flattr.com/thing/1074999/JogAmp-JOAL-Maintainer-Xerxes-Rnby

== Rami Santina ==
* http://ramisantina.com/blog/

== Mark Raynsford ==
* http://io7m.com/

== Harvey Harrison ==
* harvey.harrison [@] gmail.com
* https://github.com/hharrison

== Dominik Ströhlein ==
* http://copypastaresearch.tumblr.com/

== Wade Walker ==
* http://wadeawalker.wordpress.com/

= Support =

We are confident to make your JogAmp experience a successful story.

If you have commercial support requests or like to fund our work<br>
please feel free to contact the module maintainer [[#Contact_Maintainer|as listed above]].

Maintainer and Contacts

2013-01-16T16:29:12Z

Mraynsford: /* Contacts */

= Maintainer =

* JogAmp IT Infrastructure, Architecture and Janitor
** [[#Sven Gothel|Sven Gothel]]
* Gluegen
** [[#Sven Gothel|Sven Gothel]]
* JOAL
** [[#Xerxes Rånby|Xerxes Rånby]]
* JOGL
** [[#Sven Gothel|Sven Gothel]]
** GPU Curve Rendering
*** [[#Rami Santina|Rami Santina]]
* Java3D
** [[#Harvey Harrison|Harvey Harrison]]
* JOCL
** [[#Sven Gothel|Sven Gothel]] ''(interim)''
* Engine Support
** [[#Julien Gouesse|Julien Gouesse]]
* Maven packages
** [[#Mark Raynsford|Mark Raynsford]]
* Art (graphics, demos, ..)
** [[#Dominik Ströhlein|Dominik Ströhlein]]
* ''Open Positions''
** JOCL
** jogl-utils

= Contacts =

You can address the JogAmp Community via:
* [http://jogamp.org/ Web]
* [http://forum.jogamp.org/ Forum/Mailinglist]
* [http://https://jogamp.org/wiki/index.php/Chatroom JogAmp IRC]
* Email
** mediastream [@] jogamp.org

<div id="Contact_Maintainer">
Please feel welcome to contact the maintainers for commercial support inquiries,
specific questions you seem not fit for public discussions or to fund the work.
</div>

== Sven Gothel ==
* sgothel [@] jausoft.com
* http://jausoft.com/blog/tag/jogl/
* Contracting and funding
** via ''Göthel Software e.K., contact jogamp [@] jausoft.com''
** micro payments [http://flattr.com/thing/1028522/JogAmp-Maintainer-Sven-Gothel via Flattr]

== Julien Gouesse ==
* gouessej [@] orange.fr
* http://gouessej.wordpress.com/tag/jogl/

== Xerxes Rånby ==
* xerxes [@] gudinna.com
* http://labb.zafena.se/?category_name=jogamp
* http://twitter.com/xranby
** Micro payments via flatter: http://flattr.com/thing/1074999/JogAmp-JOAL-Maintainer-Xerxes-Rnby

== Rami Santina ==
* http://ramisantina.com/blog/

== Mark Raynsford ==
* http://io7m.com/

== Harvey Harrison ==
* harvey.harrison [@] gmail.com
* https://github.com/hharrison

== Dominik Ströhlein ==
* http://copypastaresearch.tumblr.com/

== Wade Walker ==
* http://wadeawalker.wordpress.com/

= Support =

We are confident to make your JogAmp experience a successful story.

If you have commercial support requests or like to fund our work<br>
please feel free to contact the module maintainer [[#Contact_Maintainer|as listed above]].

Main Page

2013-01-16T16:21:32Z

Mraynsford:

__NOTOC__
{| width="100%"
|-
|
<div>
Welcome to the [{{SERVER}}/ JogAmp] wiki. It documents JOGL, JOCL and JOAL, the cross-platform bindings to the OpenGL, OpenCL, and OpenAL APIs.
</div>
|-
|
{| style="width: 100%;"
|-
|style="vertical-align: top; padding: 5px; width: 50%"|<h3>Getting Started</h3>
*[[Downloading and installing JOGL|Downloading and installing]]
**[[Jogamp Versioning and Releases|Versioning and Releases]]
*[[Setting up a JogAmp project in your favorite IDE|Setting up a JogAmp project in your favorite IDE]]
*[[Jogamp SCM Repositories|Source Code Repositories]]
*[[SW Tracking|Tracking Reports]]
*[{{SERVER}}/chuck/ Build and Test Server]
|style="vertical-align: top; padding: 5px; width: 50%"|<h3>Community</h3>
*[[How to Contribute|Contribute to JogAmp]]
*[[Maintainer and Contacts]]
*[[Jogl FAQ#Bugreports & Testing|Report a bug]]
**[{{SERVER}}/bugzilla/ Bugzilla]
*[http://forum.jogamp.org/ Ask a question in the forum]
*[[chatroom|JogAmp IRC]]
|}
|-

{| style=" width: 100%;"
|-
|colspan="2"|<h1>JogAmp Modules</h1>
|-
|style="vertical-align: top; padding: 5px; width: 50%"|<h3>JOGL</h3>
*[[Jogl Overview|Overview]] [ [{{SERVER}}/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html OpenGL Evolution & JOGL] ]
*[[Jogl Tutorial|Tutorial]]
*[[Jogl FAQ|FAQ]]
*[{{SERVER}}/git/?p=jogl.git;a=blob;f=LICENSE.txt License]
*API Doc [ [{{SERVER}}/deployment/jogamp-next/javadoc/jogl/javadoc/ Public], Specs [ [{{SERVER}}/deployment/jogamp-next/javadoc/jogl/javadoc_nativewindow_spec/ Nativewindow], [{{SERVER}}/deployment/jogamp-next/javadoc/jogl/javadoc_jogl_spec/ JOGL] ] ]
*[{{SERVER}}/jogl/doc/HowToBuild.html How to Build JOGL]

|style="vertical-align: top; padding: 5px; width: 50%"|<h3>JOCL</h3>
*[[JOCL Overview|Overview]]
*[[JOCL Tutorial|Tutorial]]
*[[JOCL FAQ|FAQ]]
*[{{SERVER}}/git/?p=jocl.git;a=blob;f=LICENSE License]
*[{{SERVER}}/deployment/jogamp-next/javadoc/jocl/javadoc/ API Doc]
*[{{SERVER}}/jocl/doc/HowToBuild.html How to Build JOCL]
|-
|style="vertical-align: top; padding: 5px; width: 50%"|<h3>JOAL</h3>
*[[Joal Overview|Overview]]
*[[Joal Tutorial|Tutorial]]
*[[Joal FAQ|FAQ]]
*[{{SERVER}}/git/?p=joal.git;a=blob;f=LICENSE.txt License]
*API Doc [ [{{SERVER}}/deployment/jogamp-next/javadoc/joal/javadoc/ Public], [{{SERVER}}/deployment/jogamp-next/javadoc/joal/javadoc_dev/ Internal] ]
|style="vertical-align: top; padding: 5px; width: 50%"|<h3>GlueGen</h3>
* [[GlueGen_Wiki|Overview]]
* [{{SERVER}}/git/?p=gluegen.git;a=blob;f=LICENSE.txt License]
* [{{SERVER}}/deployment/jogamp-next/javadoc/gluegen/javadoc/ API Doc]
|}

Chatroom

2013-01-16T16:21:06Z

Mraynsford: Note IRC channel and deprecate jabber

== Freenode IRC Channel ==

Visit:

: '''irc.freenode.net'''
: '''#jogamp'''

... with any IRC client.

== Jabber (XMPP) JogAmp Channel (Deprecated) ==
: '''url: conference.jabber.org'''
: '''room: jogamp'''

'''Note: We've moved to Freenode IRC, the Jabber channel should be considered deprecated...'''

All you have to do is to create an account on e.g. http://www.jabber.org, http://jabbear.com, .. or take your existing xmpp account and join our channel with the client of your choice.
Alternatively you could also use a so called "transport server" to join even from a different IM protocol.

== New to XMPP? ==
* [http://en.wikipedia.org/wiki/Extensible_Messaging_and_Presence_Protocol XMPP on wikipedia]
* [http://xmpp.org/services/ public servers]
* [http://xmpp.org/xmpp-software/clients/ clients]

== No Client? ==
* try a web based client like [https://www.jappix.com/ jappix]

Maven And Android

2013-01-07T15:06:34Z

Mraynsford: Captions

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>10</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

<pre>
$ adb install jp4da-android/target/jp4da-android.apk
1026 KB/s (2334537 bytes in 2.221s)
pkg: /data/local/tmp/jp4da-android.apk
Success
</pre>

The program running on an ordinary Linux desktop:

[[File:blue.png|Highly complex rendering]]

The program installed on the Android emulator:

[[File:maven-android-emu1.png|The installed application]]

The program running on the Android emulator:

[[File:maven-android-emu2.png|The running application]]

File:Maven-android-emu2.png

2013-01-07T15:05:42Z

Mraynsford: The running jp4da application

The running jp4da application

File:Maven-android-emu1.png

2013-01-07T15:05:24Z

Mraynsford: The installed jp4da application

The installed jp4da application

Maven And Android

2013-01-07T15:04:58Z

Mraynsford: Additional images and command line install

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>10</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

<pre>
$ adb install jp4da-android/target/jp4da-android.apk
1026 KB/s (2334537 bytes in 2.221s)
pkg: /data/local/tmp/jp4da-android.apk
Success
</pre>

[[File:blue.png|Highly complex rendering]]

[[File:maven-android-emu1.png|The installed application]]

[[File:maven-android-emu2.png|The running application]]

Maven And Android

2013-01-07T15:01:06Z

Mraynsford: /* Excluding redundant files */

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>10</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-07T13:57:10Z

Mraynsford: /* Excluding redundant files */

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>9</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-05T14:13:58Z

Mraynsford: Missed a word

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> directory now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-05T14:13:20Z

Mraynsford: Missed a word

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> module will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-05T01:18:31Z

Mraynsford: Eliminate commas

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression against which the names of each jar file on the classpath will be tested. If a jar file is matched then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-05T01:16:11Z

Mraynsford: Missed a word

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> module explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression, against which the names of each jar file on the classpath will be tested. If a jar file is matched, then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

Maven And Android

2013-01-05T01:08:16Z

Mraynsford: /* Building */

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression, against which the names of each jar file on the classpath will be tested. If a jar file is matched, then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

[[File:blue.png|Highly complex rendering]]

File:Blue.png

2013-01-05T01:07:18Z

Mraynsford: Highly complex rendering

Highly complex rendering

Maven And Android

2013-01-05T01:05:38Z

Mraynsford: Initial version

Managing your [http://android.com Android] JOGL projects with [http://maven.apache.org Maven] is, if not effortless, at least not difficult. The following article attempts to describe one method of producing a project that will compile and run unmodified on both Android and ordinary "desktop" systems.

The article presents a [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da demo] that illustrates the organization of a trivial OpenGL application, and covers the rationale and methods behind its construction.

== Maven Modules ==

The intention in this article is to develop an extremely simple OpenGL program that simply clears the screen to a garish colour at sixty frames per second.

Typically, software projects have handled platform-specific code by using some form of conditional compilation. That is, the build system usually contains some sort of "if the current platform is <tt>P</tt>, then compile <tt>A</tt>, else compile <tt>B</tt>" statements. The recommended way to handle this with Maven is to break a project up into separate [http://maven.apache.org/guides/mini/guide-multiple-modules.html modules] so that any platform specific code is isolated and can be enabled or disabled on a per-module basis.

Assuming then that the intention is to get the program to run unmodified on Android and "anything else that can create an OpenGL window", the first thing that needs to be done is the break the program up into separate parts. Specifically:

* The "Android" frontend (the [http://developer.android.com/reference/android/app/Activity.html Activity], and associated code and classes)
* The "desktop" frontend (the usual window and context creation code, called from the main procedure in typical programs)
* The platform-independent OpenGL core

== Project ==

Firstly, a simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/pom.xml; POM] file is written that declares three submodules and very little else. As can probably be seen from the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da source browser], each of the modules has a corresponding directory each containing POM files that will be described further on in the article.

This demo project is named <tt>jp4da</tt>. Prizes won't be awarded for working out what the acronym means!

== Core ==

The platform-independent part of the program is probably the simplest, and is contained in the [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-core jp4da-core module].

A simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/src/main/java/com/io7m/examples/jp4da/Example.java Example] class that implements [http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html GLEventListener] is all that's required.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-core/pom.xml POM] file for the <tt>jp4da-core</tt> module is very simple, but does have one unusual distinction: The declared dependencies for the project are, at first glance, somewhat lacking. Typically (according to the [http://jogamp.org/wiki/index.php/Setting_up_a_JogAmp_project_in_your_favorite_IDE#Maven published instructions on setting up a JOGL Maven project]), projects will explicitly depend on the [http://search.maven.org/#search|ga|1|a%3A%22jogl-all-main%22 jogl-all-main] and [http://search.maven.org/#search|ga|1|a%3A%22gluegen-rt-main%22 gluegen-rt-main] packages in order to have Maven automatically retrieve and use the native libraries associated with each project.

The POM file for <tt>jp4da-core</tt> clearly doesn't do this.

<pre>
<dependencies>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
</dependency>
</dependencies>
</pre>

The reason for this is simple: Depending on a specific set of native libraries would be implicitly stating that module is intended to run on ''a particular platform'', as opposed to being platform-independent. Instead, the module essentially just depends on the one JOGL package that will allow the Java compiler to type-check and compile the code, without giving any consideration to how the final application will be constructed. It will also become clear, when describing the Android module, why depending on the native library packages here would be actively harmful!

== Desktop ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-desktop jp4da-desktop module] implements an extremely simple [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/src/main/java/com/io7m/examples/jp4da/DesktopExample.java main program] that opens a NEWT window and runs the event listener implemented in the <tt>jp4da-core</tt> module.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-desktop/pom.xml POM file] is similarly unsurprising, and simply declares some dependencies on the native packages that were [[#Core|specifically ignored]] earlier.

== Android ==

The [http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven/jp4da/jp4da-android jp4da-android module] implements the Android front-end for the program.

The main [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/src/main/java/com/io7m/examples/jp4da/MainActivity.java Activity] is very similar to the [[#Desktop|desktop]] code: It simply opens a window and instantiates the [[#Core|core's event listener class]]. None of this code should be particularly surprising to an Android or JOGL programmer.

The [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml POM file] for the project is, however, not quite so simple. The project file attempts to solve three separate problems:

* Process all class files with the various Android tools required to produce [http://en.wikipedia.org/wiki/Dalvik_%28software%29 Dalvik] bytecode
* Organize the correct dependencies on JOGL itself, excluding "bad" dependencies that Maven implicitly adds.
* Produce a single [http://en.wikipedia.org/wiki/APK_%28file_format%29 APK] package that follows the correct layout required by JOGL itself and includes all application assets

=== Processing class files ===

Thankfully, as of version 3.5.0, the [http://code.google.com/p/maven-android-plugin/ Android Maven plugin] handles all the necessary processing of class files without requiring any configuration on the part of the developer (apart from, perhaps, setting the <tt>ANDROID_HOME</tt> environment variable to point to the SDK tools).

With the plugin added to the [http://jogamp.org/git/?p=jogl-demos.git;a=blob;f=maven/jp4da/jp4da-android/pom.xml;#l83 build] section of the POM file, no further configuration is required to process class files.

=== Dependencies ===

For running code on Android, JOGL provides separate <tt>jogl-all-android</tt> and <tt>gluegen-rt-android</tt> jar files. However, this is where the first problem arises due to Maven's [http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html transitive dependency handling]: The <tt>jp4da-android</tt> project depends on <tt>jp4da-core</tt> which depends on <tt>jogl-all</tt>. The <tt>jp4da-android</tt> will therefore also implicitly depend on <tt>jogl-all</tt>, which will now conflict with <tt>jogl-all-android</tt>!

There are two accepted methods to handle this problem:

* Make <tt>jogl-all</tt> an [http://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#Optional_Dependencies optional dependency] of the <tt>jp4da-core</tt> project. It is then the responsibility of <tt>jp4da-android</tt> to provide a dependency that satisfies all constraints. Or:
* Have the <tt>jp4da-android</tt> explicitly ignore the <tt>jogl-all</tt> dependency of <tt>jp4da-core</tt>.

Neither method has any particular advantages or disadvantages in this case, so in the interest of keeping things explicit, the second method was chosen. The <tt>jp4da-android</tt> module explicitly ignores the <tt>jogl-all</tt> dependency and provides its own instead:

<pre>
<dependencies>
<dependency>
<groupId>com.io7m.examples.jp4da</groupId>
<artifactId>jp4da-core</artifactId>
<version>1.0.0</version>



<exclusions>
<exclusion>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>com.google.android</groupId>
<artifactId>android</artifactId>
<version>1.6_r2</version>
<scope>provided</scope>
</dependency>


<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
</dependency>

<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<scope>runtime</scope>
</dependency>
</dependencies>
</pre>

=== Producing an APK ===

Finally, it's necessary to actually produce an APK that can be installed onto devices.

The project as described so far will not work when installed, both because JOGL requires that certain files appear in specific places inside the APK and because native libraries have not been placed in the correct directory to be packaged. Additionally, the Android Maven plugin will, by default, include everything that isn't a class file from every dependency jar on the classpath into the final APK.

=== Excluding redundant files ===

So, firstly, the Android Maven plugin needs to be told not to include anything from the JOGL and GlueGen jar files. This is achieved by giving a regular expression, against which the names of each jar file on the classpath will be tested. If a jar file is matched, then the contents of the jar file are ''not'' included in the resulting APK. Essentially, specific jar files are blacklisted.

<pre>


<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<configuration>
<sdk>
<platform>8</platform>
</sdk>
</configuration>
<executions>
<execution>
<goals>
<goal>apk</goal>
</goals>
<configuration>
<excludeJarResources>
<excludeJarResource>jogl-.*\.jar$</excludeJarResource>
<excludeJarResource>gluegen-rt-.*\.jar$</excludeJarResource>
</excludeJarResources>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Copying assets and native libraries ===

Then, the standard [http://maven.apache.org/plugins/maven-dependency-plugin/ Maven dependency plugin] is used to unpack assets into the <tt>assets</tt> directory (so that the Android Maven plugin can find and process them), and also to unpack and place native libraries into the correct <tt>libs</tt> directory (again, so that the Android Maven plugin can find and process them).

The process is simple, and nothing that should be surprising to any reasonably experienced Maven user:

<pre>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.6</version>
<executions>


<execution>
<id>unpack-jogl-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>



<execution>
<id>unpack-jogl-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-android</artifactId>
<version>2.0-rc11post03</version>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/assets</outputDirectory>
<excludes>**/*.class</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>


<execution>
<id>unpack-gluegen-natives</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt</artifactId>
<version>2.0-rc11post03</version>
<classifier>natives-android-armv6</classifier>
<overWrite>true</overWrite>
<outputDirectory>${project.basedir}/libs/armeabi</outputDirectory>
<includes>lib*.so</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</pre>

=== Cleaning up ===

Finally, because the project has performed some rather non-standard (from the perspective of typical Maven usage) operations, it's good practice to use the [http://maven.apache.org/plugins/maven-clean-plugin/ Maven Clean plugin] to clean up the manually unpacked files so that each build always starts from a completely clean slate.

<pre>


<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.5</version>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/libs/armeabi</directory>
<includes>
<include>libgluegen-rt.so</include>
<include>libnewt.so</include>
<include>libjogl_mobile.so</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>



<fileset>
<directory>${project.basedir}/assets</directory>
<includes>
<include>META-INF/**</include>
<include>com/**</include>
<include>jogl/**</include>
<include>jogamp/**</include>
<include>javax/**</include>
</includes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>
</pre>

=== Building ===

Running a build from the main project directory should proceed without issue:

<pre>
$ mvn -C clean verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] jp4da-core
[INFO] jp4da-desktop
[INFO] jp4da-android
[INFO] jp4da
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] jp4da-core ........................................ SUCCESS [1.905s]
[INFO] jp4da-desktop ..................................... SUCCESS [0.658s]
[INFO] jp4da-android ..................................... SUCCESS [21.129s]
[INFO] jp4da ............................................. SUCCESS [0.001s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24.688s
[INFO] Finished at: Fri Jan 04 23:06:47 GMT 2013
[INFO] Final Memory: 22M/236M
[INFO] ------------------------------------------------------------------------
$
</pre>

The <tt>jp4da-android/target</tt> now contains a <tt>jp4da-android.apk</tt> file that can be installed onto devices or the Android emulator.

Setting up a JogAmp project in your favorite IDE

2012-11-26T13:01:12Z

Mraynsford: /* The jogamp.org test repository (optional) */

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogl Maven Central].

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

As an example, if your project uses JOGL <tt>2.0-rc11</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc11</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc11</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

=== The jogamp.org test repository (optional) ===

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

'''''Please note that packages on the jogamp test repository are subject to unannounced changes at any moment and may break existing code at any time! Do not use for production code!'''''

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Maintainer and Contacts

2012-11-15T17:27:45Z

Mraynsford: Add myself!

= Maintainer =

* Gluegen
** Sven Gothel
* JOAL
** Xerxes Rånby
* JOGL
** Sven Gothel
* JOCL
** Sven Gothel ''(interim)''
* Art
** Dominik Ströhlein
* Engine Support
** Julien Gouesse
* Maven packages
** Mark Raynsford
* ''Open Positions''
** JOCL
** jogl-utils

= Contacts =

You can address the JogAmp Community via:
* [http://jogamp.org/ Web]
* [http://forum.jogamp.org/ Forum/Mailinglist]
* JogAmp Channel
** server: conference.jabber.org room: jogamp
* Email
** mediastream [@] jogamp.org

You may also contact Individuals via:
* Sven Gothel
** sgothel [@] jausoft.com
** http://jausoft.com/blog/tag/jogl/
* Julien Gouesse
** gouessej [@] orange.fr
** http://gouessej.wordpress.com/tag/jogl/
* Xerxes Rånby
** xerxes [@] gudinna.com
** http://labb.zafena.se/?category_name=jogamp
** http://twitter.com/xranby
* Mark Raynsford
** http://io7m.com

If you have commercial support requests<br>
please feel free to contact the module maintainer.

We are confident to make your JogAmp experience a successful story.

Setting up a JogAmp project in your favorite IDE

2012-11-11T21:10:28Z

Mraynsford: Re-add old jogamp repository instructions

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogl Maven Central].

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

As an example, if your project uses JOGL <tt>2.0-rc11</tt>:

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc11</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc11</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

=== The jogamp.org test repository (optional) ===

Bleeding edge, experimental packages will continue to be made available from the
[http://jogamp.org/deployment/maven Jogamp Test Repository]. Most users won't need this, but
it can be used by adding a new profile in your <tt>~/.m2/settings.xml</tt> file that specifies
the repository:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<settings
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>jogamp</id>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>jogamp</activeProfile>
</activeProfiles>
</settings>
</code>

Maven will then check this repository for packages in addition to Maven Central when resolving dependencies.

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-11-02T14:27:59Z

Mraynsford: Maven central!

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). As of <tt>2.0-rc11</tt>, packages are pushed to
[http://search.maven.org/#search|ga|1|jogl Maven Central].

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc11</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc11</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-09-28T11:42:04Z

Mraynsford:

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains experimental support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). Right now, a test repository is available at
http://jogamp.org/deployment/maven.

=== Add the test repository to your <tt>$HOME/.m2/settings.xml</tt> ===

Add a new repository by adding a new profile (called <tt>jogamp</tt> here, but you can obviously
pick your own name if you like):

<code>
<settings>
<profiles>
<profile>
<id>jogamp</id>
<activation>
<activeByDefault>true</activeByDefault> 
</activation>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
</code>

Eventually, the <tt>jogamp</tt> artifacts will be pushed to the Central Repository and this step will become unnecessary.

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc10</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc10</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-06-27T21:06:14Z

Mraynsford: /* Add a dependency on jogl-all-main and gluegen-rt-main to your project */

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains experimental support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). Right now, a test repository is available at
http://jogamp.org/deployment/maven.

=== Add the test repository to your <tt>$HOME/.m2/settings.xml</tt> ===

Add a new repository by adding a new profile (called <tt>jogamp</tt> here, but you can obviously
pick your own name if you like):

<code>
<settings>
<profiles>
<profile>
<id>jogamp</id>
<activation>
<activeByDefault>true</activeByDefault> 
</activation>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
</code>

Eventually, the <tt>jogamp</tt> artifacts will be pushed to the Central Repository and this step will become unnecessary.

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc9</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc9</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

An example project is available in the <tt>maven</tt> subdirectory of the <tt>jogl-demos</tt> project
[http://jogamp.org/git/?p=jogl-demos.git;a=tree;f=maven].

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-06-27T21:03:22Z

Mraynsford: /* Add the test repository to your $HOME/.m2/settings.xml */

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains experimental support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). Right now, a test repository is available at
http://jogamp.org/deployment/maven.

=== Add the test repository to your <tt>$HOME/.m2/settings.xml</tt> ===

Add a new repository by adding a new profile (called <tt>jogamp</tt> here, but you can obviously
pick your own name if you like):

<code>
<settings>
<profiles>
<profile>
<id>jogamp</id>
<activation>
<activeByDefault>true</activeByDefault> 
</activation>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
</code>

Eventually, the <tt>jogamp</tt> artifacts will be pushed to the Central Repository and this step will become unnecessary.

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc9</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc9</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-06-27T21:01:54Z

Mraynsford: Fix link

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains experimental support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). Right now, a test repository is available at
http://jogamp.org/deployment/maven.

=== Add the test repository to your <tt>$HOME/.m2/settings.xml</tt> ===

Add a new repository by adding a new profile (called <tt>jogamp</tt> here, but you can obviously
pick your own name if you like):

<code>
<settings>
<profiles>
<profile>
<id>jogamp</id>
<activation>
<activeByDefault>true</activeByDefault> 
</activation>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
</code>

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc9</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc9</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.

Setting up a JogAmp project in your favorite IDE

2012-06-27T21:00:15Z

Mraynsford: Add initial maven instructions

__TOC__

These instructions assume that you've created a project in your favorite IDE, and now you want your project to be able to use a JogAmp library like JOGL, JOCL, JOAL, or GlueGen. We use JOGL as an example below, but these instructions work equally well for any other JogAmp library.

= Download a JogAmp library =

If you haven't done so already, download and extract the JogAmp library you want to use. For example, to download and extract JOGL, see the instructions at [[Downloading and installing JOGL]].

To use a JogAmp library you'll do three things:

* Add its JAR files to the Java classpath
* Add its native libraries in one of two ways:
** Either place its native JAR files in the same directory as the library JAR files
** Or add its native library files(the <tt>.dll</tt>,<tt>.so</tt>, and <tt>.jnilib</tt> files) to the Java library path
* Optional: Associate the *-java-src.zip files with the corresponding JAR files.

Each IDE has a slightly different way to do these things, as we show below. Using the native JAR files is usually slightly easier than using the native library files directly, and native JARs make it possible for all platforms' libraries to coexist in one project, so this is the recommended method.

Please note that all JogAmp libraries depend on the GlueGen runtime libraries. These are included in every JogAmp library for convenience, but are only required once in the classpath and library path of your project.

= Eclipse IDE project =

Probably the simplest way to use JOGL in an Eclipse project is to create another Eclipse project to contain the JOGL JARs, then make your project depend on this new JOGL project. In the example below, I include only the 64-bit Windows native JARs, but you can put native JARs for as many platforms as you wish together into the JOGL Eclipse project.

=== Create a JOGL project ===

* Put all the JOGL code JARs, native JARs for all platforms you wish to support, and source ZIP files in a directory called "JOGL" in your workspace directory.
* Click "File > New > Java Project". Type "JOGL" as the project name and click "Next".
[[File:Eclipse_project_setup_01_create_project.png|300px|thumb|none|Create JOGL project]]
* Click the "Libraries" tab, select the native JARs, and click "Remove".
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
* Expand the remaining JARs. For each of them, double-click "Source attachment", click "Workspace...", navigate to the corresponding <tt>*-java-src.zip</tt> file in the project, select it, click "OK", and click "OK" again to dismiss the "Source Attachment Configuration" dialog. The JARs should look like this when you're done:
[[File:Eclipse_project_setup_03_JARs_with_source_attached.png|300px|thumb|none|Attach source to JARs]]
* Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
[[File:Eclipse_project_setup_04_order_and_export.png|300px|thumb|none|Exporting JOGL JARs]]

=== Add dependency on the JOGL project ===

* Right-click your project and click "Properties".
* Select the "Java Build Path" on the left, then click the "Projects" tab on the right.
* Click the "Add..." button, check "JOGL", and click "OK".
* Your dependent project should look like this. Click "OK" to dismiss the "Properties" dialog.
[[File:Eclipse_project_setup_05_project_dependency.png|300px|thumb|none|JOGL project dependency]]

That's it! Your project can now use the library.

= Eclipse IDE user library =

If you don't want to put JOGL in a separate Eclipse project, you can put it in a user library instead. The drawback to this is that the user library is defined in your .metadata directory and contains absolute paths, so it's hard to share with others. But for a non-shared project this works fine.

=== Create a user library ===

* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select all the non-native JARs, then click "Open".
* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Expand each non-native JAR in the list
** Double-click "Source attachment", type the module's source zip name, (e.g. <tt>jogl-java-src.zip</tt> for the JAR file <tt>jogl.all.jar</tt>), and click "OK".
** If you're using native library files:
*** Double-click "Native library location", type the directory where native library files are stored, and click "OK".
[[File:Eclipse_setup_02_set_native_library_locations.png|300px|thumb|none|Set native library locations]]
* Click "OK" to exit Preferences dialog.

=== Add the user library to your project's dependencies ===

* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
[[File:Eclipse_setup_03_add_library_to_project.png|300px|thumb|none|Add library to project]]
* Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
[[File:Eclipse_setup_04_add_JOGL_library_to_project.png|300px|thumb|none|Add JOGL library to project]]
* Click "OK" to dismiss the Properties dialog.

That's it! You can now use the library in your project.

= IntelliJ IDEA =
=== Add a library dependency to your project ===

* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "+" button on the right, then select "Library... > Java".
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Navigate to the directory where you extracted the JARs, select it, and click "OK".
[[File:IntelliJ_setup_02_find_library.png|300px|thumb|none|Find library]]
* Click "OK" to dismiss the Configure Library dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "OK" to dismiss the Project Structure dialog. The external libraries in your project should now look like this if you're using native JAR files:
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
or like this if you're using native library files:
[[File:IntelliJ_setup_04_external_library.png|300px|thumb|none|Native library files]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files.
* Otherwise, if you're using native library files:
** Click "Run > Edit Configurations".
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
[[File:IntelliJ_setup_05_run_configuration.png|300px|thumb|none|Edit run configuration]]
** Click "OK" to dismiss the Run/Debug Configurations dialog.

That's it! You can now use the library in your project.

= NetBeans IDE =
=== Create a library and add it to your project ===

* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOGL" for the library name and click "OK".[[File:NetBeans_setup_01_create_library.png|300px|thumb|none|Create library]]
* Click "Add JAR/Folder...", then navigate to the directory you extracted the JAR files, select them and click "Add JAR/Folder".
* Click "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add Library dialog.[[File:NetBeans_setup_02_add_library.png|300px|thumb|none|Add library]]
* Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.[[File:NetBeans_setup_03_libraries_in_project.png|300px|thumb|none|Libraries in project]]

* If you're using native JAR files:
** Make sure the <tt>gluegen-rt-natives-*-*.jar</tt> and <tt>jogl-all-natives-*-*.jar</tt> files for each platform you want to run on are in the same directory as the other JAR files. The native JAR files don't need to be added to the classpath.
* Otherwise, if you're using native library files:
** Click "Run > Set Project Configuration > Customize...". Select "Run" on the left if it isn't selected already.
** Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Options" box.
** NOTE: If the library path has spaces in it, you must put quotes around it (at least on Windows) or you may get an odd NoClassDefFoundError when you try to run.[[File:NetBeans_setup_04_native_library_path.png|300px|thumb|none|Native library path]]
** Click "OK" to dismiss the Project Properties dialog.

That's it! You can now use the library in your project.

= Maven =

Jogamp now contains experimental support for Maven, for the <tt>jogl</tt> components (<tt>jocl</tt>
and <tt>joal</tt> support is forthcoming). Right now, a test repository is available at
[http://jogamp.org/deployment/maven|http://jogamp.org/deployment/maven].

=== Add the test repository to your <tt>$HOME/.m2/settings.xml</tt> ===

Add a new repository by adding a new profile (called <tt>jogamp</tt> here, but you can obviously
pick your own name if you like):

<code>
<settings>
<profiles>
<profile>
<id>jogamp</id>
<activation>
<activeByDefault>true</activeByDefault> 
</activation>
<repositories>
<repository>
<id>jogamp-remote</id>
<name>jogamp test mirror</name>
<url>http://www.jogamp.org/deployment/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
</code>

=== Add a dependency on <tt>jogl-all-main</tt> and <tt>gluegen-rt-main</tt> to your project ===

<code>
<dependencies>
<dependency>
<groupId>org.jogamp.gluegen</groupId>
<artifactId>gluegen-rt-main</artifactId>
<version>2.0-rc9</version>
</dependency>
<dependency>
<groupId>org.jogamp.jogl</groupId>
<artifactId>jogl-all-main</artifactId>
<version>2.0-rc9</version>
</dependency>
</dependencies>
</code>

Maven will pull all of the dependencies the next time you attempt to build the project.

= vi and other text editors =
=== Create your project with the editor of your choice ===
* For example, to open vi, simply type <tt>vi</tt> and press <return>.
* Type all your code, then save it.

=== Compile and run your project from the command line ===
* We assume your JOGL JAR files are in a directory called <tt>jar</tt>. If you're using native JARs, we assume they're also in the <tt>jar</tt> directory. If you're using native library files, we assume they're in a directory called <tt>lib</tt>.

* First compile your program. We assume all your code is in a single file called <tt>name/someone/MyProject.java</tt>.
** Windows: Type <tt>javac -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar" name\someone\MyProject.java</tt>
** Linux/MacOS X: Type <tt>javac -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar" name/someone/MyProject.java</tt>

* Then run your project. We assume your main class is <tt>name.someone.MyProject</tt>. If you're using native JARs:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." name.someone.MyProject</tt>
* If you're using native library files:
** Windows: Type <tt>java -classpath "jar\gluegen-rt.jar;jar\jogl.all.jar;." -Djava.library.path=lib name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl.all.jar:." -Djava.library.path=lib name.someone.MyProject</tt>

That's it! You can now use the library in your project.