Setting up a JogAmp project in your favorite IDE: Difference between revisions

From JogampWiki
Jump to navigation Jump to search
(joined with intellij and netbeans howto + made more generic to apply for all jogamp projects)
(Added -Djogamp.gluegen.UseTempJarCache=false to instructions for command line)
(44 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__TOC__
__TOC__


It's very simple to set up a project of your favourite IDE to use a JogAmp library. These instructions assume you've already created a new project in the IDE.
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 project =
= Download a JogAmp library =


If you haven't done so already, download and extract for example JOGL as described at [[Downloading_and_installing_JOGL]].
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 be able to use a JogAmp library you will have to add the jar files to the classpath and the native files to the library path of your projects run configuration.  
To use a JogAmp library you'll do three things:
Please note that all projects depend on the GlueGen runtime libraries which are for convenience reasons included in every JogAmp project but only required once in the classpath/library path of your application.
 
* 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]]
* Remove the native JARs from the project, leaving only gluegen-rt.jar and jogl-all.jar.
[[File:Eclipse_project_setup_02_remove_native_JARs.png|300px|thumb|none|Remove native JARs]]
          NOTE: The gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar are not
          required in the classpath by JOGL, but 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.


= Eclipse IDE =
=== Create a user library ===
=== Create a user library ===
You can make your new Eclipse project depend directly on all the JARs and native libraries, but it's inconvenient to do that every time you create a new project. Creating a user library bundles all the files together so you can include them in one step.


* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click "Window > Preferences", then select "Java > Build Path > User Libraries" on the left.
* Click the "New..." button, type "JOAL", "JOCL", "JOGL" or "GlueGen RT" for the library name, and click "OK".
* Click the "New..." button, type "JOGL" for the library name, and click "OK".
* Click the "Add JARs..." button, navigate to the directory where you've stored the JARs, select them, then click "Open".
[[File:Eclipse_setup_01_create_user_library.png|300px|thumb|none|Create user library]]
* Expand the jar in the list, double-click "Native library location", type the directory where native library files are stored, and click "OK".
* 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.
* Click "OK" to exit Preferences dialog.


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


* Right-click your project in the Package Explorer and clock "Properties".
* Right-click your project in the Package Explorer and click "Properties".
* Select "Java Build Path" and click the "Libraries" tab.
* 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".
* 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.
* Click "OK" to dismiss the Properties dialog.


Line 31: Line 81:


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


* Click "File > Project Structure".
* Click "File > Project Structure".
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Select "Modules" on the left, then click the "Dependencies" tab on the right.
* Click the "Add..." button, then click "Library...".
* Click the "+" button on the right, then select "Library... > Java".
* Type "JOAL", "JOCL", "JOGL" or "GlueGen RT" as the library name.
[[File:IntelliJ_setup_01_add_library.png|300px|thumb|none|Add library]]
* Click "Attach JAR Directories...", navigate to the directory where you extracted the JARs and click "OK".
* 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.
* Click "OK" to dismiss the Configure Library dialog.
* Click "OK" to dismiss the Project Structure dialog.
[[File:IntelliJ_setup_03_configure_library.png|300px|thumb|none|Configure library]]
* Click "Run > Edit Configurations".
* 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:
* Type <tt>-Djava.library.path=your/path/to/native/library/files</tt> in the "VM Parameters" box.
[[File:IntelliJ_setup_04_external_library_native_JARs.png|300px|thumb|none|Native JARs]]
* Click "OK" to dismiss the Run/Debug Configurations dialog.
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.
That's it! You can now use the library in your project.


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


* Right-click your project and click "Properties".
* Right-click your project and click "Properties".
* Select "Libraries" on the left and click "Add Library...".
* Select "Libraries" on the left and click "Add Library...".
* Click the "Create" button, then type "JOAL", "JOCL", "JOGL" or "GlueGen RT" for the library name and click "OK".
* 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 "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 "OK" to dismiss the Customize Library dialog.
* Click "Add Library" to dismiss the Add 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.
* 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]]
* 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.
* If you're using native JAR files:
* Click "OK" to dismiss the Project Properties dialog.
** 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.
That's it! You can now use the library in your project.


= Vi =
= Maven =
=== Open a shell of your choice ===
$vi <return>


That's it!
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 -Djogamp.gluegen.UseTempJarCache=false name.someone.MyProject</tt>
** Linux/MacOS X: Type <tt>java -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar:." -Djava.library.path=lib -Djogamp.gluegen.UseTempJarCache=false name.someone.MyProject</tt>
 
That's it! You can now use the library in your project.

Revision as of 03:39, 3 March 2016

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 .dll,.so, and .jnilib 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, 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".
Create JOGL project
  • Remove the native JARs from the project, leaving only gluegen-rt.jar and jogl-all.jar.
Remove native JARs
          NOTE: The gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar are not
          required in the classpath by JOGL, but 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 *-java-src.zip 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:
Attach source to JARs
  • Click the "Order and Export" tab. Check both JOGL JARs, then click "Finish".
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.
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".
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 gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar 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. jogl-java-src.zip for the JAR file jogl-all.jar), 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".
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.
Add library to project
  • Click "Add Library...", select "User Library", click "Next", check "JOGL", and click "Finish".
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".
Add library
  • Navigate to the directory where you extracted the JARs, select it, and click "OK".
Find library
  • Click "OK" to dismiss the Configure Library dialog.
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:
Native JARs

or like this if you're using native library files:

Native library files
  • If you're using native JAR files:
    • Make sure the gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar 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 -Djava.library.path=your/path/to/native/library/files in the "VM Parameters" box. Note that paths with spaces must be double-quoted on Windows.
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".
    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.
    Add library
  • Click "OK" to dismiss the Project Properties dialog. The libraries in your project should look like this.
    Libraries in project
  • If you're using native JAR files:
    • Make sure the gluegen-rt-natives-*-*.jar and jogl-all-natives-*-*.jar 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 -Djava.library.path=your/path/to/native/library/files 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.
      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 2.0-rc11, packages for all the JogAmp projects have been pushed to 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 vi 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 jar. If you're using native JARs, we assume they're also in the jar directory. If you're using native library files, we assume they're in a directory called lib.
  • First compile your program. We assume all your code is in a single file called name/someone/MyProject.java.
    • Windows: Type javac -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar" name\someone\MyProject.java
    • Linux/MacOS X: Type javac -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar" name/someone/MyProject.java
  • Then run your project. We assume your main class is name.someone.MyProject. If you're using native JARs:
    • Windows: Type java -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar;." name.someone.MyProject
    • Linux/MacOS X: Type java -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar:." name.someone.MyProject
  • If you're using native library files:
    • Windows: Type java -classpath "jar\gluegen-rt.jar;jar\jogl-all.jar;." -Djava.library.path=lib -Djogamp.gluegen.UseTempJarCache=false name.someone.MyProject
    • Linux/MacOS X: Type java -classpath "jar/gluegen-rt.jar:jar/jogl-all.jar:." -Djava.library.path=lib -Djogamp.gluegen.UseTempJarCache=false name.someone.MyProject

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