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