***************************************************************************** Copyright (c) 2006, Colorado School of Mines and others. All rights reserved. This software and accompanying materials are made available under the terms of the Common Public License - v1.0, which accompanies this distribution, and is available at http://www.eclipse.org/legal/cpl-v10.html ***************************************************************************** Java Native Interface (JNI) libraries for the Mines Java Toolkit ---------------------------------------------------------------- The purpose of this project is to provide libraries of native (non-Java) code for use with the Mines Java Toolkit (JTK). In the JTK, We load these Java Native Interface (JNI) libraries dynamically via Java's System.loadLibrary method. Examples include our JNI libraries that wrap OpenGL (for 3-D graphics) and LAPACK (for dense linear algebra). ***************************************************************************** Note: we recently switched to using JOGL, an almost-standard Java binding for the OpenGL. Therefore, although the instructions here explain how to build our package edu.mines.jtk.opengl, other packages in the Mines JTK do not use it. We keep it around, just in case we have to switch back for some reason. ***************************************************************************** Most programmers will not need to build these libraries from source, as pre-compiled binaries are included with source code for the Mines JTK. Indeed, before attempting to build this project jtkjni, you should first build the project jtk and understand how that process works. One reason that you might build our JNI libraries from source is that you need these libraries for a platform that we do not yet support. Currently, we support 32-bit x86 systems running Linux and Windows and 64-bit x64 systems running Linux. Note: if you modify (or port, or translate, or ...) our source code, then you have created a "derived work", and should review carefully the terms of the license that accompanies this software. Getting the source code ----------------------- To build our JNI libraries from source, you must first use Subversion (SVN) client software to checkout (co) the source code from our SVN repository: http://boole.mines.edu/jtkjni. If you are using Linux, an SVN client is likely available with your Linux distribution. If not yet installed, perhaps you simply need to install it. In a terminal window, type "svn". If that command is found, then (1) cd to the directory that will contain your jtkjni directory and (2) type the command svn co http://boole.mines.edu/jtkjni This command will create a directory jtkjni in your current working directory. For Windows, we recommand that you download and install TortoiseSVN from http://tortoisesvn.tigris.org. TortoiseSVN integrates nicely with the Windows Explorer. After installing TortoiseSVN, (1) make a folder jtkjni (in the same folder as your jtk folder), (2) right-click on your jtkjni folder and select "SVN checkout ..." from the menu, (3) enter the URL http://boole.mines.edu/jtkjni, and (4) enter the output path, including the jtkjni directory. After SVN checkout, you should have a directory jtkjni/trunk/ with the following subdirectories: bin/ - platform-dependent scripts (e.g., antrun.bat and antrun.sh) jar/ - jar files (e.g., ant.jar) lib/ - platform-specific libraries (e.g., liblapack.a) src/ - source code files (e.g., edu/mines/jtk/opengl/Gl.cpp) Tools for building ------------------ To build the JNI libraries for the Mines JTK, you need: * J2SE JDK 5.0 (or later): http://java.sun.com/j2se * Apache Ant 1.6.2 (or later): http://ant.apache.org * g++ (GCC) 3.2.3 (or later): http://www.mingw.org (for Windows only) * OpenGL header files GL/gl.h, GL/glext.h, and so on. All of these tools are freely available on the web. However, if building on Windows, the download page for MinGW may be confusing. You want a file with a name like "MinGW-3.1.0-1.exe", although later versions should work as well. This exe file is an installer for Windows, and it may appear somewhere in the middle of the MinGW download page. On Windows, we like to put tools such as the JDK, Ant, and MinGW in a folder named "C:\pro\". This folder name is shorter than "C:\Program Files" and contains no spaces, which makes it easy to specify in scripts. OpenGL header files may be platform-specific. They are freely available, though with licenses that do not permit us to redistribute them. We require OpenGL version 1.5 (or higher). For Linux systems and Windows systems with MinGW, you probably have files GL/gl.h and GL/glext.h, but the latter file GL/glext.h may be an old version. You need a GL/glext.h that uses the macro GL_VERSION_1_5 inside. If necessary, download a recent GL/glext.h and replace the one you have. For example, on Windows, you would put GL/glext.h in the folder mingw\include\. Building the libraries ---------------------- In your jtkjni/trunk/bin/ directory are scripts for running Ant. Choose an appropriate script for your platform, and copy it to some directory that is in your PATH. From any directory, you will want to type the command antrun and have this script be found. You may of course rename this script to anything you like. In your copy of the antrun script, edit the environment variables so that the script will find your JDK, Ant, and GCC. Then cd to your jtkjni/trunk/ directory (the one that contains build.xml) and type antrun. This command should build the JNI libraries for the Mines Java Toolkit. Type antrun -p to learn more about other build targets, such as clean and install. To install, your jtk and jtkjni directories must be located side-by-side in the same directory. JNI libraries built with MinGW depend on the file mingwm10.dll provided here (in jtkjni\trunk\lib\windows\x86\) and with the MinGW distribution. On windows, this file should be installed in the same directory as the JNI libraries.