update to JPL snapshot v09141999, with minor tweaks (from Brian

Jepson <bjepson@home.com>)

p4raw-id: //depot/perl@4159

1 files changed, 158 insertions, 5 deletions

diff --git a/jpl/README b/jpl/README
index eb900f024c..57f52c4f71 100644
--- a/jpl/README
+++ b/jpl/README
@@ -9,12 +9,13 @@ from the network.  Don't expect not to be surprised occasionally.
 
 Requirements
 ------------
-Perl 5.005_02 (or later) must be compiled and installed as a shared library
-(libperl.so).  I had to use the system's malloc.  JPL was originally built
-and tested with 5.004_04 and early Java 1.1 development kits.  This version
-has not been well tested under 5.005_02, so you can expect some rough edges.
+Under Solaris and Linux (and other Unix-like systems), Perl 5.005 (or later)
+must be compiled and installed as a shared library (libperl.so).  I had to use
+the system's malloc.  JPL was originally built and tested with 5.004_04 and
+early Java 1.1 development kits.  This version has not been well tested under
+other versions, so you can expect some rough edges.
 
-You need JDK 1.1.  On Solaris 1.1.5 has been verified to work.  Linux
+You need JDK 1.1.  On Solaris, 1.1.5 has been verified to work.  Linux
 users can try the latest version (1.1.3 or later) available from (for
 example):
 
@@ -28,6 +29,21 @@ You may need to ensure that all files under the ../jpl directory are writable.
 install-jpl expects to be run with super-user privileges so that it can
 put things in the right places.
 
+Microsoft Windows
+-----------------
+Only a subset of JPL works under Microsoft Windows.  This subset includes
+the JNI extension and the JPL module.  This is enough for you to embed
+Java in Perl, but not Perl in Java.
+
+This has only been tested with the Sun JDK 1.1.8. I haven't tested it
+with JDK 1.2 (aka Java 2) or any Microsoft implementation of Java.
+
+Kaffe
+-----
+You might notice some mention of Kaffe (www.kaffe.org) in the source files. 
+This is because some preliminary work is being done in this area, but JPL
+doesn't yet work with Kaffe.
+
 What the heck is JPL?
 ---------------------
 JPL is a hybrid (to use the polite term) language.  It's basically Java
@@ -58,6 +74,25 @@ file it generates.
 
 Installation
 ------------
+There are two ways to install JPL.
+
+The first way gives you the ability to embed Perl in Java programs. You
+can also call back into Java from your embedded Perl programs. This should
+work well with most JDKs, and is the only option for people using a JDK
+that uses green threads (see your JDK documentation). 
+
+The second way lets you embed Java in Perl, but doesn't provide support
+for the other direction. This is good, in theory, if you need to work with
+a lot of Java classes from within Perl.  I say "in theory," because this 
+doesn't actually work a lot of the time.  To use this second way, you
+must be using a JDK with native threads.
+
+At this point, the second way is the only way to use JPL under Microsoft 
+Windows. Oddly enough, this is the only platform under which the second 
+way works!
+
+Installation the First Way (All of JPL)
+---------------------------------------
 Run "install-jpl".  You have to tell it whether you want to use the
 current directory for JPL_HOME or some other directory.  Everything
 else should take care of itself, except that after install-jpl
@@ -68,6 +103,124 @@ before any JPL applications can be compiled under the current shell.
     csh:  eval `setvars -csh`
     perl: eval `setvars -perl`;
 
+install-jpl has been tested under:
+
+    Solaris 2.5.1 SPARC, GCC 2.8.0, Perl 5.005_03, JDK 1.1.7
+    Debian 2.1 x86, Perl 5.005_60, JDK 1.1.7v3
+
+********************
+Solaris 2.5.1 Users:
+********************
+
+NOTE: Under Solaris 2.5.1, you may get an error message when install-jpl
+builds Sample.jpl:
+
+    You must install a Solaris patch to run this version of the Java 
+    runtime.  Please see the README and release notes for more 
+    information.
+    Exiting.
+
+  This is apparently a spurious message, and it has been reported to 
+  Sun.  Although this message aborts the installation, all of JPL is 
+  installed by the time this message is reached. To recover and continue, 
+  run setvars as described above, cd to the Sample directory, and type
+  'make' to continue building. You can then run 'java Sample' to test the 
+  example.
+
+  Unfortunately, each time you use 'make' to build a JPL application,
+  it will abort when it tries to run 'perl -c' on the generated .pl
+  file.  However, you can continue building by typing 'make' again.
+
+Just-JNI (call into Java from Perl only)
+----------------------------------------
+
+This has been tested with:
+
+    Debian 2.1 SPARC, Perl 5.005_60, JDK 1.2 beta (crashes with AWT, though)
+    Windows NT 4.0 SP4, ActivePerl 519, JDK 1.1.8, Visual C++
+    Solaris 7, Perl 5.005_03, JDK 1.1.6, GCC 2.8.1
+
+Solaris 7 Note (this probably applies to all native thread situations):
+
+    Native threads were tricky. I had to build my own Perl, configured with:
+
+    sh Configure -Dprefix=/opt/perl5.005 -Duseshrplib -Doptimize=-g \
+                 -Uusemymalloc -D cc=gcc -Dusethreads -d
+
+    When Configure let me edit config.sh, I changed libs to:
+
+    libs='-lthread -lsocket -lnsl -ldl -lm -lposix4 -lpthread -lc -lcrypt'
+
+    The leading -lthread is the only thing I had to add.
+
+How do I do this crazy thing?
+
+1) Cd into the JPL directory. Type the following:
+
+    perl Makefile.PL
+    make
+    make install
+
+   Under windows, that's:
+
+    perl Makefile.PL
+    nmake
+    nmake install
+
+3) cd into the JNI directory (cd ../JNI or cd ..\JNI)   
+
+4) We now need to compile and make the Closer.class available to your 
+   JPL program.  Closer is a WindowListener that closes the Frame we 
+   make in the test program.
+
+   It seems that we've managed to fix the problem with CLASSPATH not
+   getting propagated to the JVM, so if '.' is in your CLASSPATH, you
+   should be able to compile Closer.java and leave it in the current
+   directory:
+
+       javac Closer.java
+
+5) Make the demo:
+
+    a) If you are on Windows, copy typemap.win32:
+
+        copy typemap.win32 typemap
+
+       (this step will probably go away when we clean up some of the
+        WIN32 #defines)
+
+    b) type the following:
+
+        perl Makefile.PL
+        make
+        make test
+
+       Under Windows:
+
+        perl Makefile.PL
+        nmake
+        nmake test
+
+
+    c) if all went well, type:
+
+        make install
+
+       or, under Windows:
+
+        nmake install
+
+Mailing List
+------------
+To subscribe to the jpl mailing list, send an email message to 
+jpl-subscribe@perl.org.
+
+CVS Access
+----------
+Information on accessing the bleeding edge JPL via CVS can be found at:
+
+    http://users.ids.net/~bjepson/jpl/cvs.html
+
 More Info
 ---------