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