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 Linux (and other Unix-like systems), Perl 5.005 (or later)
  13 must be compiled and installed as a shared library (libperl.so).  I had to use
  14 the system's malloc.  JPL was originally built and tested with 5.004_04 and
  15 early Java 1.1 development kits.  This version has not been well tested under
  16 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.  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 The get_jdk directory contains a script that will download JDK (but not
  25 the patch file above) off of the net for you.  (This presumes you've
  26 already installed the modules mentioned in ../README.)
  27
  28 You may need to ensure that all files under the ../jpl directory are writable.
  29 install-jpl expects to be run with super-user privileges so that it can
  30 put things in the right places.
  31
  32 Microsoft Windows
  33 -----------------
  34 Only a subset of JPL works under Microsoft Windows.  This subset includes
  35 the JNI extension and the JPL module.  This is enough for you to embed
  36 Java in Perl, but not Perl in Java.
  37
  38 This has only been tested with the Sun JDK 1.1.8. I haven't tested it
  39 with JDK 1.2 (aka Java 2) or any Microsoft implementation of Java.
  40
  41 Kaffe
  42 -----
  43 You might notice some mention of Kaffe (www.kaffe.org) in the source files.
  44 This is because some preliminary work is being done in this area, but JPL
  45 doesn't yet work with Kaffe.
  46
  47 What the heck is JPL?
  48 ---------------------
  49 JPL is a hybrid (to use the polite term) language.  It's basically Java
  50 in which the methods can optionally be implemented by Perl code.  A
  51 preprocessor called "JPL::Compile" looks at your .jpl file and spits
  52 out the appropriate .java, .c, .h, .pl, and .so files to accomplish the
  53 desired task.  Hopefully a lot of those files can go away in the future
  54 as jpl mutates into a Perl-to-Java compiler.  The long-term goal is for
  55 jpl to be able to take a pure Perl file and spit out a java .class
  56 file.  This initial version of JPL is an attempt to begin to mesh the
  57 semantics of Java and Perl.  Some people may find it useful in its
  58 current form, but you should know right up front that we've still got a
  59 ways to go with it.  A journey of a thousand miles continues with the
  60 second step...
  61
  62 JPL Syntax
  63 ----------
  64 JPL syntax is trivial, given that you know Java and Perl.  Pretend like
  65 you're writing a native Java method, but say "perl" instead of
  66 "native", and then instead of omitting the body of the method, put your
  67 Perl code in double curlies.  (See Sample.jpl for an example.)
  68
  69 Calling back from Perl to Java is done through the JNI (Java Native
  70 Interface).  No weird transmogrifications are done by the preprocessor
  71 to your Perl code--it's all normal Perl.  The preprocessor just wraps
  72 it up into funny subroutines you don't see unless you peek at the .pl
  73 file it generates.
  74
  75 Installation
  76 ------------
  77 There are two ways to install JPL.
  78
  79 The first way gives you the ability to embed Perl in Java programs. You
  80 can also call back into Java from your embedded Perl programs. This should
  81 work well with most JDKs, and is the only option for people using a JDK
  82 that uses green threads (see your JDK documentation).
  83
  84 The second way lets you embed Java in Perl, but doesn't provide support
  85 for the other direction. This is good, in theory, if you need to work with
  86 a lot of Java classes from within Perl.  I say "in theory," because this
  87 doesn't actually work a lot of the time.  To use this second way, you
  88 must be using a JDK with native threads.
  89
  90 At this point, the second way is the only way to use JPL under Microsoft
  91 Windows. Oddly enough, this is the only platform under which the second
  92 way works!
  93
  94 Installation the First Way (All of JPL)
  95 ---------------------------------------
  96 Run "install-jpl".  You have to tell it whether you want to use the
  97 current directory for JPL_HOME or some other directory.  Everything
  98 else should take care of itself, except that after install-jpl
  99 writes the setvars program, you are responsible to invoke it properly
 100 before any JPL applications can be compiled under the current shell.
 101
 102     sh:   eval `setvars -sh`
 103     csh:  eval `setvars -csh`
 104     perl: eval `setvars -perl`;
 105
 106 install-jpl has been tested under:
 107
 108     Solaris 2.5.1 SPARC, GCC 2.8.0, Perl 5.005_03, JDK 1.1.7
 109     Debian 2.1 x86, Perl 5.005_60, JDK 1.1.7v3
 110
 111 ********************
 112 Solaris 2.5.1 Users:
 113 ********************
 114
 115 NOTE: Under Solaris 2.5.1, you may get an error message when install-jpl
 116 builds Sample.jpl:
 117
 118     You must install a Solaris patch to run this version of the Java
 119     runtime.  Please see the README and release notes for more
 120     information.
 121     Exiting.
 122
 123   This is apparently a spurious message, and it has been reported to
 124   Sun.  Although this message aborts the installation, all of JPL is
 125   installed by the time this message is reached. To recover and continue,
 126   run setvars as described above, cd to the Sample directory, and type
 127   'make' to continue building. You can then run 'java Sample' to test the
 128   example.
 129
 130   Unfortunately, each time you use 'make' to build a JPL application,
 131   it will abort when it tries to run 'perl -c' on the generated .pl
 132   file.  However, you can continue building by typing 'make' again.
 133
 134 Just-JNI (call into Java from Perl only)
 135 ----------------------------------------
 136
 137 This has been tested with:
 138
 139     Debian 2.1 SPARC, Perl 5.005_60, JDK 1.2 beta (crashes with AWT, though)
 140     Windows NT 4.0 SP4, ActivePerl 519, JDK 1.1.8, Visual C++
 141     Solaris 7, Perl 5.005_03, JDK 1.1.6, GCC 2.8.1
 142
 143 Solaris 7 Note (this probably applies to all native thread situations):
 144
 145     Native threads were tricky. I had to build my own Perl, configured with:
 146
 147     sh Configure -Dprefix=/opt/perl5.005 -Duseshrplib -Doptimize=-g \
 148                  -Uusemymalloc -D cc=gcc -Dusethreads -d
 149
 150     When Configure let me edit config.sh, I changed libs to:
 151
 152     libs='-lthread -lsocket -lnsl -ldl -lm -lposix4 -lpthread -lc -lcrypt'
 153
 154     The leading -lthread is the only thing I had to add.
 155
 156 How do I do this crazy thing?
 157
 158 1) Cd into the JPL directory. Type the following:
 159
 160     perl Makefile.PL
 161     make
 162     make install
 163
 164    Under windows, that's:
 165
 166     perl Makefile.PL
 167     nmake
 168     nmake install
 169
 170 3) cd into the JNI directory (cd ../JNI or cd ..\JNI)
 171
 172 4) We now need to compile and make the Closer.class available to your
 173    JPL program.  Closer is a WindowListener that closes the Frame we
 174    make in the test program.
 175
 176    It seems that we've managed to fix the problem with CLASSPATH not
 177    getting propagated to the JVM, so if '.' is in your CLASSPATH, you
 178    should be able to compile Closer.java and leave it in the current
 179    directory:
 180
 181        javac Closer.java
 182
 183 5) Make the demo:
 184
 185     a) If you are on Windows, copy typemap.win32:
 186
 187         copy typemap.win32 typemap
 188
 189        (this step will probably go away when we clean up some of the
 190         WIN32 #defines)
 191
 192     b) type the following:
 193
 194         perl Makefile.PL
 195         make
 196         make test
 197
 198        Under Windows:
 199
 200         perl Makefile.PL
 201         nmake
 202         nmake test
 203
 204
 205     c) if all went well, type:
 206
 207         make install
 208
 209        or, under Windows:
 210
 211         nmake install
 212
 213 Mailing List
 214 ------------
 215 To subscribe to the jpl mailing list, send an email message to
 216 jpl-subscribe@perl.org.
 217
 218 CVS Access
 219 ----------
 220 Information on accessing the bleeding edge JPL via CVS can be found at:
 221
 222     http://users.ids.net/~bjepson/jpl/cvs.html
 223
 224 More Info
 225 ---------
 226
 227 You can look at the Sample and Test directories.
 228
 229 Perhaps the most important bit of advice we can give you is to watch
 230
 231     http://perl.oreilly.com
 232
 233 for further information on how to get further information.
 234
 235 Have the appropriate amount of fun.