-
Notifications
You must be signed in to change notification settings - Fork 20
/
README
341 lines (250 loc) · 12.8 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
Polyglot Extensible Compiler Framework (Version 2.7.1)
------------------------------------------------------
Overview
--------
This is release 2.7 of the Polyglot extensible compiler framework.
It contains many improvements over previous releases of Polyglot,
including better debugging support in the PPG parser generator,
preservation of Javadoc comments in translated code, improvements to
the pth testing harness, and many bug fixes, especially related to
generics.
More details on the Javadoc-related changes can be found in the file
doc/release-2.7-notes/PolyglotJavadocPreservation.html.
Contents
--------
Since you are reading this file, you have already downloaded and
unpacked the Polyglot distribution. Your installation directory
contains the following sub-directories:
- src: the complete source code of Polyglot
- src/polyglot: the Polyglot base compiler and Java5 extension
- examples: some example Polyglot extensions
- bin: scripts for invoking the base Polyglot compiler, Java5
Polyglot extension, and the Polyglot test harness
- tools/java_cup: tweaked version of the Java CUP parser generator 0.10k.
- tools/ppg: the Polyglot parser generator, an extension of Java CUP
- tools/pth: Polyglot test harness
- doc: documentation
- doc/api: Javadoc descriptions of Polyglot classes
- tests: test cases for the Polyglot Java language extension
- testsjl5: test cases for the Polyglot Java5 language extension
- skel: a skeleton Polyglot extension, useful for creating new
extensions
Disclaimer
----------
Polyglot is research software. Over time, some of the interfaces in the
framework may change. This may require some extensions to be changed to
conform to the new interfaces. Also, Polyglot is not well-documented; in
particular, some of the Javadoc is missing or out-of-date. We are working on
writing better documentation. For future updates, watch this web page:
http://www.cs.cornell.edu/Projects/polyglot
If you use Polyglot, we'd appreciate your letting us know. Send comments
and bug reports to [email protected].
Requirements
------------
Polyglot builds on Unix, Mac OS X, and on Windows using the Cygwin
environment. We recommend that you use JDK 7 or later. You will
experience problems with versions of the JDK older than 7. You must ensure
that java and javac are in your path, and that the JAVA_HOME environment
variable is set to the installation directory of the JDK. Polyglot is compiled
with the Ant build tool (https://ant.apache.org).
Polyglot uses the JFlex scanner generator. The JFlex jar file is
included in the Polyglot distribution. Polyglot is distributed under
LGPL, but JFlex is distributed under GPL. See the JFlex web site
http://jflex.de
for updates and the source code of JFlex. The output of JFlex
inherits the copyright of the specification--licensed under
LGPL in Polyglot's case. It is possible to substitute your own
lexical analysis or to use another lexer generator such as JLex
(http://www.cs.princeton.edu/~appel/modern/java/JLex/), but this
is not encouraged.
Creating an extension
---------------------
To see how to create your own extensions, see the file doc/Overview.txt.
Running Polyglot
----------------
Polyglot is compiled with the Ant build tool (http://jakarta.apache.org/ant).
1. Go to the root directory of the Polyglot installation (the directory this
README is in). We'll call this directory $POLYGLOT from now on.
$ cd $POLYGLOT
2. Run ant to build the shell script bin/jlc.
$ ant bin
This need only be performed once.
3. Optionally: add $POLYGLOT/bin to your PATH environment variable.
4. You are now ready to try out Polyglot.
To compile a language extension source file, do:
$ jlc -ext <extname> <source-file>
For example:
$ jlc -ext jl5 testsjl5/Generics01.jl5
or equivalently:
$ jlc -extclass polyglot.ext.jl5.ExtensionInfo \
testsjl5/Generics01.jl5
The latter usage is convenient if the extension is not implemented as
a subpackage in the polyglot source tree.
To compile using the base compiler, just leave out the -ext option:
$ jlc File.jl
This should produce a file called File.java that is almost identical to
File.jl.
Java 5, 7, 8 language extensions
-------------------------------------
Polyglot supports Java 5 language extensions with a Polyglot compiler
extension, which can be found in the directory
$POLYGLOT/src/polyglot/ext/jl5. This compiler extension currently
suports all of the Java 5 language extensions except for annotations.
To compile a Java 5 source file, invoke the Polyglot compiler with the
jl5 extension:
$ jlc -extclass polyglot.ext.jl5.ExtensionInfo \
testsjl5/Generics01.jl5
The script jl5c in the $POLYGLOT/bin directory provides a convenient
way to invoke the jl5 extension.
$ jl5c testsjl5/Generics01.jl5
By default, jl5c will translate Java 1.5 code to Java 1.5 code. With
the command line option "-removeJava5isms", jl5c will translate Java
1.5 code to Java 1.4. It will, however, translate enumerations using
the class java.lang.Enum as the superclass of enumeration classes. The
command line option "-enumImplClass <fully-qualified-class-name>"
allows the user to specify a different class to use as the superclass
of enumeration classes. See $POLYGLOT/testsjl5/java-src/MyEnum.java
for an example of a suitable class to use as the superclass of
enumeration classes.
Similarly, the script "jl7c" and "jl8c" can be used to compile Java 7
and Java 8 programs respectively.
Building Polyglot
-----------------
The source release includes a fully compiled version of Polyglot.
However, you may want to build the base compiler and the installed extensions
yourself. Follow these steps:
1. First, ensure javac is in your path and that you are using JDK 1.5
or later. Also ensure JFlex.jar is in your classpath or is in the lib
directory.
2. Change to the $POLYGLOT directory.
$ cd $POLYGLOT
3. Run ant to build the base compiler.
$ ant
Optionally, create some extensions in the examples directory:
$ ant coffer pao
Class files will be placed in the $POLYGLOT/classes directory.
You may optionally, do:
$ ant jar
$ ant coffer-jar pao-jar
to create jar files in the lib directory for Polyglot and for each extension.
4. Update PATH and CLASSPATH.
Add $POLYGLOT/bin to your PATH environment variable. Add
$POLYGLOT/classes (or $POLYGLOT/lib/polyglot.jar) and
$POLYGLOT/lib/java_cup.jar to your CLASSPATH.
5. You are now ready create your own extensions to Java. See
doc/Overview.txt for instructions on building an extension. See the
instructions earlier in this file for how to use the compiler.
Credits and Acknowledgments
---------------------------
The Polyglot project is jointly supervised by Prof. Andrew Myers (Cornell
University), by Prof. Stephen Chong (Harvard University), and by Prof.
Nathaniel Nystrom (U. Lugano).
Version 2.7 of Polyglot was prepared largely through the work of
Chinawat Isradisaikul (Cornell), though many others have contributed
to it.
Many people have contributed substantially to the development of Polyglot,
including:
Owen Arden Scott Moore
Karthik Bellur Andrew Myers
Michael Brukman Nate Nystrom
Stephen Chong Xin Qi
Michael Clarkson Naveen Sastry
Matt Harren Jeffrey Sheldon
Chin Isradisaikul Dan Spoonhower
Rob Jellinek Steve Zdancewic
Aleksey Kliger Yizhou Zhang
Samarth Lad Lantian Zheng
Jed Liu Xin Zheng
Nick Mathewson Sam Zhou
The Polyglot class file parsing code (src/polyglot/types/reflect)
is derived from code written for the BLOAT bytecode optimizer written
by Nathaniel Nystrom, David Whitlock, and Antony Hosking at
Purdue University. See http://sourceforge.net/projects/javabloat.
The code is used here and released under both LGPL and EPL by permission.
The Base64 code (polyglot.util.Base64) is derived from public domain
code by Robert Harder <[email protected]>. See http://iharder.net/base64.
The JL5 extension was based on the "Polyglot for Java 5" project by Milan
Stanojevic and Todd Millstein
(http://www.cs.ucla.edu/~todd/research/polyglot5.html), with additional input
from Vincent Cavé.
The following people have provided patches:
Pavel Avgustinov <[email protected]>
Hubert Chao <[email protected]>
Alvin Cheung <[email protected]>
Robert Fuhrer <[email protected]>
Michael George <[email protected]>
Patrick Lam <[email protected]>
Keunwoo Lee <[email protected]>
Ondrej Lhotak <[email protected]>
Matthew Loring <[email protected]>
Oege de Moor <[email protected]>
Igor Peshansky <[email protected]>
Krishnaprasad Vikram <[email protected]>
Grant Wang <[email protected]>
Alessandro Warth <[email protected]>
The development of the Polyglot project has been supported by a
number of funding sources, including DARPA Contract F30602-99-1-0533,
monitored by USAF Rome Laboratory, ONR Grant N00014-01-1-0968, NSF
Grants CNS-0208642, CNS-0430161, and CCF-0133302, an Alfred P. Sloan
Research Fellowship, and an Intel Research Ph.D. Fellowship.
Restrictions on distribution
----------------------------
This release of the Polyglot distribution is governed by the LGPL
license as described by the following copyright notice.
Polyglot extensible compiler framework
Copyright (C) 2000-2016 Polyglot project group, Cornell University
Copyright (C) 2006-2012 IBM Corporation
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
A copy of the GNU Lesser General Public License can be found in the file
LICENSE.LGPL, included in this distribution.
Excluding the exceptions listed below, all files in this release are also
released under the Eclipse Public License. A copy of the license can be
found in the file LICENSE.Eclipse, included in this distribution.
The following files are covered by the LGPL, but are NOT released under
the Eclipse Public License:
src/polyglot/ext/jl/parse/java12.cup
lib/polyglot.jar
lib/coffer.jar
lib/pao.jar
src/java_cup (and all files in subdirectories)
lib/java_cup.jar
Additionally, any build targets derived from the above files are not
released under the Eclipse Public License.
CUP Parser Generator Copyright Notice, License, and Disclaimer
---------------------------------------------------------------
Copyright 1996-2015 by C. Scott Ananian, Frank Flannery, Dan Wang, Andrew W.
Appel, and Michael Petter. Permission to use, copy, modify, and distribute this
software and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all copies and that
both the copyright notice and this permission notice and warranty disclaimer
appear in supporting documentation, and that the names of the authors or their
employers not be used in advertising or publicity pertaining to distribution of
the software without specific, written prior permission.
The authors and their employers disclaim all warranties with regard to this
software, including all implied warranties of merchantability and fitness.
In no event shall the authors or their employers be liable for any special,
indirect or consequential damages or any damages whatsoever resulting from
loss of use, data or profits, whether in an action of contract, negligence or
other tortious action, arising out of or in connection with the use or
performance of this software.
BLOAT Copyright Notice, License, and Disclaimer
-----------------------------------------------
Polyglot includes code dervied from BLOAT (Bytecode Level Optimization and
Analysis tool for Java(tm)). All files in the distribution of BLOAT are
Copyright 1997-2001 by the Purdue Research Foundation of Purdue University.
BLOAT was written by Nathaniel Nystrom, David Whitlock, and Antony Hosking
at Purdue University. BLOAT is licensed under the LGPL and has the same
restrictions on distributed as Polyglot. See the file LICENSE.LGPL for
a copy.
BASE64 Copyright Notice, License, and Disclaimer
------------------------------------------------
The Base64 code (polyglot.util.Base64) is derived from public domain
code by Robert Harder <[email protected]>. See http://iharder.net/base64.
Java is a trademark of Oracle Corporation.