jpl/README

   1 Copyright 1998, O'Reilly & Associates, Inc.
   2
   3 This package may be copied under the same terms as Perl itself.
   4
   5 Disclaimers
   6 -----------
   7 This is a work in progress, and relies on bleeding-edge technology
   8 from the network.  Don't expect not to be surprised occasionally.
   9
  10 Requirements
  11 ------------
  12 Under Solaris and GNU/Linux (and other Unix-like systems), Perl 5.005 (or
  13 later) must be compiled and installed as a shared library (libperl.so).  I
  14 had to use the system's malloc.  JPL was originally built and tested with
  15 5.004_04 and early Java 1.1 development kits.  This version has not been
  16 well tested under other versions, so you can expect some rough edges.
  17
  18 You need JDK 1.1.  On Solaris, 1.1.5 has been verified to work.  GNU/Linux
  19 users can try the latest version (1.1.3 or later) available from (for
  20 example):
  21
  22   ftp://ftp.blackdown.org/pub/Linux/JDK/1.1.3/updates/libjava-1.1.3v2-1.tar.gz
  23
  24 (GNU/Linux users can also try Kaffe (see below).)
  25
  26 The get_jdk directory contains a script that will download JDK (but not
  27 the patch file above) off of the net for you.  (This presumes you've
  28 already installed the modules mentioned in ../README.)
  29
  30 You may need to ensure that all files under the ../jpl directory are writable.
  31 install-jpl expects to be run with super-user privileges so that it can
  32 put things in the right places.
  33
  34 Microsoft Windows
  35 -----------------
  36 Only a subset of JPL works under Microsoft Windows.  This subset includes
  37 the JNI extension and the JPL module.  This is enough for you to embed
  38 Java in Perl, but not Perl in Java.
  39
  40 This has only been tested with the Sun JDK 1.1.8. I haven't tested it
  41 with JDK 1.2 (aka Java 2) or any Microsoft implementation of Java.
  42
  43 Kaffe
  44 -----
  45 You might notice some mention of Kaffe (www.kaffe.org) in the source files.
  46 This is because support has been added for Kaffe for JNI:: and JPL::.  In
  47 other words, you can now call to Java from Perl using Kaffe.
  48
  49 You'll likely need the a checkout circa 2000-12-03 or later from Kaffe's
  50 CVS.  It has been verified that Kaffe 1.0.5 definitely *will not work*.
  51 Kaffe 1.0.6 might work, but the CVS tree definitely works (as of
  52 2000-12-06).
  53
  54 You can get the CVS tree from:
  55
  56 cvs -z3 -d ':pserver:readonly@cvs.kaffe.org:/cvs/kaffe' checkout kaffe
  57
  58 (password is 'readonly')
  59
  60 What the heck is JPL?
  61 ---------------------
  62 JPL is a hybrid (to use the polite term) language.  It's basically Java
  63 in which the methods can optionally be implemented by Perl code.  A
  64 preprocessor called "JPL::Compile" looks at your .jpl file and spits
  65 out the appropriate .java, .c, .h, .pl, and .so files to accomplish the
  66 desired task.  Hopefully a lot of those files can go away in the future
  67 as jpl mutates into a Perl-to-Java compiler.  The long-term goal is for
  68 jpl to be able to take a pure Perl file and spit out a java .class
  69 file.  This initial version of JPL is an attempt to begin to mesh the
  70 semantics of Java and Perl.  Some people may find it useful in its
  71 current form, but you should know right up front that we've still got a
  72 ways to go with it.  A journey of a thousand miles continues with the
  73 second step...
  74
  75 JPL Syntax
  76 ----------
  77 JPL syntax is trivial, given that you know Java and Perl.  Pretend like
  78 you're writing a native Java method, but say "perl" instead of
  79 "native", and then instead of omitting the body of the method, put your
  80 Perl code in double curlies.  (See Sample.jpl for an example.)
  81
  82 Calling back from Perl to Java is done through the JNI (Java Native
  83 Interface).  No weird transmogrifications are done by the preprocessor
  84 to your Perl code--it's all normal Perl.  The preprocessor just wraps
  85 it up into funny subroutines you don't see unless you peek at the .pl
  86 file it generates.
  87
  88 Installation
  89 ------------
  90 There are two ways to install JPL.
  91
  92 The first way gives you the ability to embed Perl in Java programs. You
  93 can also call back into Java from your embedded Perl programs. This should
  94 work well with most JDKs, and is the only option for people using a JDK
  95 that uses green threads (see your JDK documentation).
  96
  97 The second way lets you embed Java in Perl, but doesn't provide support
  98 for the other direction. This is good, in theory, if you need to work with
  99 a lot of Java classes from within Perl.  I say "in theory," because this
 100 doesn't actually work a lot of the time.  To use this second way, you
 101 must be using a JDK with native threads. Please see README.JUST-JNI for
 102 details.
 103
 104 At this point, the second way is the only way to use JPL under Microsoft
 105 Windows, and probably the only way to use JPL if you're using a version
 106 of Perl compiled by someone else (such as the Perl that comes with RedHat).
 107
 108 Installation the First Way (All of JPL)
 109 ---------------------------------------
 110 Run "install-jpl".  You have to tell it whether you want to use the
 111 current directory for JPL_HOME or some other directory.  Everything
 112 else should take care of itself, except that after install-jpl
 113 writes the setvars program, you are responsible to invoke it properly
 114 before any JPL applications can be compiled under the current shell.
 115
 116     sh:   eval `setvars -sh`
 117     csh:  eval `setvars -csh`
 118     perl: eval `setvars -perl`;
 119
 120 install-jpl has been tested under:
 121
 122     Solaris 2.5.1 SPARC, GCC 2.8.0, Perl 5.005_03, JDK 1.1.7
 123     Debian 2.1 x86, Perl 5.005_60, JDK 1.1.7v3
 124
 125 ********************
 126 Solaris 2.5.1 Users:
 127 ********************
 128
 129 NOTE: Under Solaris 2.5.1, you may get an error message when install-jpl
 130 builds Sample.jpl:
 131
 132     You must install a Solaris patch to run this version of the Java
 133     runtime.  Please see the README and release notes for more
 134     information.
 135     Exiting.
 136
 137   This is apparently a spurious message, and it has been reported to
 138   Sun.  Although this message aborts the installation, all of JPL is
 139   installed by the time this message is reached. To recover and continue,
 140   run setvars as described above, cd to the Sample directory, and type
 141   'make' to continue building. You can then run 'java Sample' to test the
 142   example.
 143
 144   Unfortunately, each time you use 'make' to build a JPL application,
 145   it will abort when it tries to run 'perl -c' on the generated .pl
 146   file.  However, you can continue building by typing 'make' again.
 147
 148 Mailing List
 149 ------------
 150 To subscribe to the jpl mailing list, send an email message to
 151 jpl-subscribe@perl.org.
 152
 153 CVS Access
 154 ----------
 155 Information on accessing the bleeding edge JPL via CVS can be found at:
 156
 157     http://users.ids.net/~bjepson/jpl/cvs.html
 158
 159 More Info
 160 ---------
 161
 162 You can look at the Sample and Test directories, as well as the ../eg
 163 directory for examples.
 164
 165 Perhaps the most important bit of advice we can give you is to watch
 166
 167     http://perl.oreilly.com
 168
 169 for further information on how to get further information.
 170
 171 Have the appropriate amount of fun.