Copyright 1998, O'Reilly & Associates, Inc.

This package may be copied under the same terms as Perl itself.

Disclaimers
-----------
This is a work in progress, and relies on bleeding-edge technology
from the network.  Don't expect not to be surprised occasionally.

Requirements
------------
Under Solaris and Linux (and other Unix-like systems), Perl 5.005_60 (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
users can try the latest version (1.1.3 or later) available from (for
example):

  ftp://ftp.blackdown.org/pub/Linux/JDK/1.1.3/updates/libjava-1.1.3v2-1.tar.gz

The get_jdk directory contains a script that will download JDK (but not
the patch file above) off of the net for you.  (This presumes you've
already installed the modules mentioned in ../README.)

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
in which the methods can optionally be implemented by Perl code.  A
preprocessor called "JPL::Compile" looks at your .jpl file and spits
out the appropriate .java, .c, .h, .pl, and .so files to accomplish the
desired task.  Hopefully a lot of those files can go away in the future
as jpl mutates into a Perl-to-Java compiler.  The long-term goal is for
jpl to be able to take a pure Perl file and spit out a java .class
file.  This initial version of JPL is an attempt to begin to mesh the
semantics of Java and Perl.  Some people may find it useful in its
current form, but you should know right up front that we've still got a
ways to go with it.  A journey of a thousand miles continues with the
second step...

JPL Syntax
----------
JPL syntax is trivial, given that you know Java and Perl.  Pretend like
you're writing a native Java method, but say "perl" instead of
"native", and then instead of omitting the body of the method, put your
Perl code in double curlies.  (See Sample.jpl for an example.)

Calling back from Perl to Java is done through the JNI (Java Native
Interface).  No weird transmogrifications are done by the preprocessor
to your Perl code--it's all normal Perl.  The preprocessor just wraps
it up into funny subroutines you don't see unless you peek at the .pl
file it generates.

Installation
------------
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
writes the setvars program, you are responsible to invoke it properly
before any JPL applications can be compiled under the current shell.

    sh:   eval `setvars -sh`
    csh:  eval `setvars -csh`
    perl: eval `setvars -perl`;

Installation under Microsoft Windows
------------------------------------

Still pretty rough!!!

1) Edit the SETVARS.PL script in the top-level jpl directory.

2) Cd into the JPL directory. Type the following:

    perl Makefile.PL
    nmake
    nmake install

3) cd into the JNI directory.  

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.

   I'm still not sure how JNI deals with the CLASSPATH environment
   variable. So far, I'm convinced it ignores it.

   Under JDK 1.1.8 on Win32, I found that the following paths were available
   in my classpath:

       C:\jdk1.1.8\bin\..\classes
       C:\jdk1.1.8\bin\..\lib\classes.zip
       C:\jdk1.1.8\bin\..\lib\classes.jar
       C:\jdk1.1.8\bin\..\lib\rt.jar
       C:\jdk1.1.8\bin\..\lib\i18n.jar

   This tells me two things: the CLASSPATH is determined relative to
   the location of javai.dll (C:\jdk1.1.8\bin\), and that if I create
   a directory called C:\jdk1.1.8\classes, I can dump my own custom
   classes in it.

   You need to do this now.  These instructions will vary depending on
   where you installed the JDK:

       mkdir C:\jdk1.1.8\classes
       javac Closer.java
       copy Closer.class C:\jdk1.1.8\classes

5) Make the demo:

    a) copy perlcrt.lib into the JNI directory:

        copy c:\perl\lib\core\PerlCrt.lib 
 
    b) Copy typemap.win32:

        copy typemap.win32 typemap

    c) Copy JNIConfig.win32:

        copy JNIConfig.win32 JNIConfig

    d) edit JNIConfig to suit your installation

    e) type the following:

        perl Makefile.PL
        nmake
        nmake test

    f) if all went well, type:

        nmake install

Mailing List
------------
To subscribe to the jpl-users mailing list, send a message containing the
word "subscribe" to jpl-users-request@as220.org. You will then receive a
message explaining more about the list, and how to unsubscribe from it.

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
---------

You can look at the Sample and Test directories, as well as the ../eg
directory for examples.

Perhaps the most important bit of advice we can give you is to watch

    http://perl.oreilly.com

for further information on how to get further information.

Have the appropriate amount of fun.
