YA resync with mainstem, including VMS patches from others
[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------------
c529f79d 12Under Solaris and Linux (and other Unix-like systems), Perl 5.005 (or later)
13must be compiled and installed as a shared library (libperl.so). I had to use
14the system's malloc. JPL was originally built and tested with 5.004_04 and
15early Java 1.1 development kits. This version has not been well tested under
16other versions, so you can expect some rough edges.
93e0cdbd 17
c529f79d 18You need JDK 1.1. On Solaris, 1.1.5 has been verified to work. 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
24The get_jdk directory contains a script that will download JDK (but not
25the patch file above) off of the net for you. (This presumes you've
26already installed the modules mentioned in ../README.)
27
28You may need to ensure that all files under the ../jpl directory are writable.
29install-jpl expects to be run with super-user privileges so that it can
30put things in the right places.
31
c529f79d 32Microsoft Windows
33-----------------
34Only a subset of JPL works under Microsoft Windows. This subset includes
35the JNI extension and the JPL module. This is enough for you to embed
36Java in Perl, but not Perl in Java.
37
38This has only been tested with the Sun JDK 1.1.8. I haven't tested it
39with JDK 1.2 (aka Java 2) or any Microsoft implementation of Java.
40
41Kaffe
42-----
43You might notice some mention of Kaffe (www.kaffe.org) in the source files.
44This is because some preliminary work is being done in this area, but JPL
45doesn't yet work with Kaffe.
46
93e0cdbd 47What the heck is JPL?
48---------------------
49JPL is a hybrid (to use the polite term) language. It's basically Java
50in which the methods can optionally be implemented by Perl code. A
51preprocessor called "JPL::Compile" looks at your .jpl file and spits
52out the appropriate .java, .c, .h, .pl, and .so files to accomplish the
53desired task. Hopefully a lot of those files can go away in the future
54as jpl mutates into a Perl-to-Java compiler. The long-term goal is for
55jpl to be able to take a pure Perl file and spit out a java .class
56file. This initial version of JPL is an attempt to begin to mesh the
57semantics of Java and Perl. Some people may find it useful in its
58current form, but you should know right up front that we've still got a
59ways to go with it. A journey of a thousand miles continues with the
60second step...
61
62JPL Syntax
63----------
64JPL syntax is trivial, given that you know Java and Perl. Pretend like
65you'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
67Perl code in double curlies. (See Sample.jpl for an example.)
68
69Calling back from Perl to Java is done through the JNI (Java Native
70Interface). No weird transmogrifications are done by the preprocessor
71to your Perl code--it's all normal Perl. The preprocessor just wraps
72it up into funny subroutines you don't see unless you peek at the .pl
73file it generates.
74
75Installation
76------------
c529f79d 77There are two ways to install JPL.
78
79The first way gives you the ability to embed Perl in Java programs. You
80can also call back into Java from your embedded Perl programs. This should
81work well with most JDKs, and is the only option for people using a JDK
82that uses green threads (see your JDK documentation).
83
84The second way lets you embed Java in Perl, but doesn't provide support
85for the other direction. This is good, in theory, if you need to work with
86a lot of Java classes from within Perl. I say "in theory," because this
87doesn't actually work a lot of the time. To use this second way, you
88must be using a JDK with native threads.
89
90At this point, the second way is the only way to use JPL under Microsoft
91Windows. Oddly enough, this is the only platform under which the second
92way works!
93
94Installation the First Way (All of JPL)
95---------------------------------------
93e0cdbd 96Run "install-jpl". You have to tell it whether you want to use the
97current directory for JPL_HOME or some other directory. Everything
98else should take care of itself, except that after install-jpl
99writes the setvars program, you are responsible to invoke it properly
100before 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
c529f79d 106install-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********************
112Solaris 2.5.1 Users:
113********************
114
115NOTE: Under Solaris 2.5.1, you may get an error message when install-jpl
116builds 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
134Just-JNI (call into Java from Perl only)
135----------------------------------------
136
137This 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
143Solaris 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
156How do I do this crazy thing?
157
1581) 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
1703) cd into the JNI directory (cd ../JNI or cd ..\JNI)
171
1724) 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
1835) 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
213Mailing List
214------------
215To subscribe to the jpl mailing list, send an email message to
216jpl-subscribe@perl.org.
217
218CVS Access
219----------
220Information on accessing the bleeding edge JPL via CVS can be found at:
221
222 http://users.ids.net/~bjepson/jpl/cvs.html
223
93e0cdbd 224More Info
225---------
226
227You can look at the Sample and Test directories, as well as the ../eg
228directory for examples.
229
230Perhaps the most important bit of advice we can give you is to watch
231
232 http://perl.oreilly.com
233
234for further information on how to get further information.
235
236Have the appropriate amount of fun.