Commit | Line | Data |
---|---|---|
93e0cdbd GS |
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 | ------------ | |
b83c0eaa GS |
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. | |
93e0cdbd | 17 | |
b83c0eaa | 18 | You need JDK 1.1. On Solaris, 1.1.5 has been verified to work. Linux |
db4a4bfe GS |
19 | users can try the latest version (1.1.3 or later) available from (for |
20 | example): | |
93e0cdbd GS |
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 | ||
b83c0eaa GS |
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 | ||
93e0cdbd GS |
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 | ------------ | |
b83c0eaa GS |
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 | --------------------------------------- | |
93e0cdbd GS |
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 | ||
b83c0eaa GS |
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 | ||
93e0cdbd GS |
224 | More Info |
225 | --------- | |
226 | ||
227 | You can look at the Sample and Test directories, as well as the ../eg | |
228 | directory for examples. | |
229 | ||
230 | Perhaps the most important bit of advice we can give you is to watch | |
231 | ||
232 | http://perl.oreilly.com | |
233 | ||
234 | for further information on how to get further information. | |
235 | ||
236 | Have the appropriate amount of fun. |