GCJNI (A Haskell / Java bridge based on GreenCard and the Java Native Interface) Release Notes for source release, Feb. 28, 2002 ----------------------------------------------- Pre-requisites: - An installation of Hugs98 or ghc 5.02.2. I have tested the release with Hugs98Feb2001, Hugs98Dec2001 and most of the releases in between, and they all worked fine. (Linux users will have to compile hugs for use with pthreads. See NOTE below in section "Building From Sources") I have also tested the release with ghc 5.02.2, and now use this as my baseline development platform. - The Java 2 SDK version 1.4 standard edition. This is available from: http://java.sun.com/j2se/1.4/ (I have also tested with JDK 1.3, and everything worked fine, but there were some minor changes to the JNI in 1.4, so your mileage may vary.) - GreenCard 2.03 This is available from: http://www.haskell.org/greencard (I have also tested with GreenCard 2.01, but I strongly recommend 2.03, as the installation and build process has improved considerably.) - GNU make 3.76 or higher (Windows users: GNU make is included with Cygwin, see below). - (Win32 users ONLY): Cygwin, a POSIX emulation layer for Windows. This includes the bash shell and GNU make, needed for compiling from sources. Cygwin is available from: http://sources.redhat.com/cygwin/ Building From Sources: ---------------------- *** NOTE (for Linux hugs users): You MUST use a version of hugs98 compiled for use with pthreads. To build hugs with pthreads support, pass the --with-pthreads option to configure. For example: $ cd /some/path/Hugs98Dec2001/src/unix $ ./configure --prefix=/usr/local --with-pthreads $ cd .. $ make install 1. Install the JDK and GreenCard. *** NOTE!! (for users of ghc 5.02.2): There is a bug in ghc's dependency generation (the -M option) concerning its handling of embedded spaces. Unfortunately, the current binary release of GreenCard for Windows installs itself by default into the directory "C:\Program Files\GreenCard". As a workaround, you should obtain the source distribution of greencard, unzip the distribution into some path with no embedded spaces and build it there. (Windows users: the Makefile assumes that greencard is in "C:\greencard\gc-2.03") This bug should be fixed in the upcoming 5.02.3 release. 2. Set up your environment variables for using Java: Linux users: i) Set JDK to the directory containing your Java Development Kit. (This is /usr/java/j2sdk1.4.0 on my system) ii) set JREDIR to $JDK/jre/lib/i386 iii) Add $JDK/bin to your PATH environment variable. iv) Add the following to your LD_LIBRARY_PATH environment variable: $JREDIR:$JREDIR/native_threads:$JREDIR/client If you are a bash user, you can achieve all of the above by adding the following lines to your .bashrc or .bash_profile and re-starting: export JDK=/usr/java/j2sdk1.4.0 export JREDIR=$JDK/jre/lib/i386 export PATH=$JDK/bin:$PATH export LD_LIBRARY_PATH=$JREDIR:$JREDIR/native_threads:$JREDIR/client:$LD_LIBRARY_PATH Windows users: I reccomend setting environment variables via the "System" control panel applet (accessible via Start...Settings...Control Panel...System...Advanced). i) Set JDK to the directory containing your Java Development Kit. (This is C:\j2sdk1.4.0 on my system) ii) Add the following to your PATH environment variable: %JDK%\bin;%JDK%\jre\bin\client;%JDK%\jre\bin 3. Edit the file ./config--local.mk to reflect how things are set up on your machine. 4. Type 'make'. 5. If all went well, type (as root on Linux machines) 'make install'. 6. Try a quick test. ghc users: We provide a stand-alone Makefile that you can use in your own projects. $ cd test (edit Makefile.ghc- to ensure the right settings for paths as needed) $ make -f Makefile.ghc- $ ./jniTest Hello World from Haskell $ hugs users: $ cd test $ runhugs -98 Main main [...] Hello World from Haskell $ 7. (Optional, but recommended): Add GenBindings.jar to your CLASSPATH. This will allow you to execute the "GenBindings" utility which generates type-safe Haskell bindings for Java code classes using reflection. Add $(prefix)/lib/java/GenBindings.jar to your CLASSPATH environment variable, where $(prefix) is the path defined in config--local.mk. Linux users: Edit your .bash_profile. For my system, I use: export CLASSPATH=$CLASSPATH:/usr/local/lib/java/GenBindings.jar (Windows users: You should edit CLASSPATH using the control panel applet, and should use ';' as a separator between CLASSPATH components. On my system, my CLASSPATH is ...;c:\haskell\lib\GenBindings.jar;...) 8. (For Hugs Users): Set up your hugs path: You need to add the directories $(GC_DIR)/lib/hugs and $(prefix)/lib/hugs/gcjni to your path, where $(prefix) and $(GC_DIR) are the locations specified in config--local.mk. Linux users: Add something like the following to your .bash_profile: export HUGSFLAGS=-P"/usr/local/src/greencard/gc-2.03/lib/hugs:/usr/local/lib/hugs/gcjni::" (Note the extra trailing ':' in the above! This is critical). Windows Users: Use the control panel applet to set the HUGSFLAGS environment variable. Be sure to use '\' in paths, and ';' to seperate path components. For example, I use: -Pc:greencard\gc-2.03\lib\hugs;c:\haskell\lib\hugs\gcjni;; (Note the extra trailing ';' in the above! This is critical). Where to From Here ------------------ You can have a look at test/JNITest.hs and Prog.java to find numerous examples of the low-level API. Most of the API is a straightforward Haskell binding for corresponding functions in the Java Native Interface (JNI). More detailed information about the JNI is available from: http://java.sun.com/products/jdk/1.2/docs/guide/jni/ If you wish to use the GenBindings tool to automatically generate type-safe Haskell bindings from Java class libraries, I encourage you to download and install "Haven", a purely functional interface to the Java2D renderer, which uses gcjni and the GenBindings tool. Haven is available from: http://www.haskell.org/haven $Id: RELNOTES.txt,v 1.5 2002/03/03 21:41:16 antony Exp $