JogAmp JAR File Handling

= Native JAR Files =

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

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

= Applet / JNLP Usage =


 * Using JOGL in a Java Applet
 * Using JOGL in Java Web Start

A short copy is included in the static page [/jogl/doc/deployment/JOGL-DEPLOYMENT.html#TraditionalApplets JOGL Deployment for traditional Applets].

= Custom Bundling =

Multi-Jar
[/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-.jar: gluegen-rt-natives-.jar jogl-all-natives-.jar

A combination with Fat-Jar is possible.

Fat-Jar
[/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.

Further more, 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//' 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//libLala1.so /natives//libLala2.so

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

One-Jar
[/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 [/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.

Eclipse
Native JAR files and their respective base JAR files can be bundled in [/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