polyj - compiler for Java with parametric polymorphism
polyj [-r <source root>] [-c <classfile dest>] [-t <translation dest>]
[-I <instantiation package>] [-classpath <classpath>] [-sync] [-force]
[-gOvV] <source file> ...
Table of Contents
polyj is a compiler for the PolyJ language, an extension to the Java
language that supports parametric polymorphism. For more information about
PolyJ, see http://www.pmg.lcs.mit.edu/polyj.
The PolyJ language includes support for generic programming in the
form of parameterized types. Like some other proposals
for adding genericity to Java, PolyJ provides constrained
parametric polymorphism. Unlike some, it uses the
signature constraints called where clauses, which
provide more flexibility when composing a program. It
also allows basic types like "int" to be used as parameter types.
Unlike some other systems, PolyJ treats instantiation types as
first-class types that may be used wherever a
type may be used -- particularly, in run-time casts and
instanceof exressions.
The PolyJ compiler may be used to compile both ordinary Java classes (with
the extension ".java") and PolyJ classes (with the extension ".pj").
Classes from both languages can easily be combined to form a program. This
works because polyj is really a source-to-source translator; it translates
PolyJ source files into Java programs, then invokes a Java compiler of your
choice.
-r <source root>
Specify the root of the project. When the compiler needs to search for
source files, it looks not only under all the directories in the class
path, but also under the source root. For example, if a source file
imported a class foo.bar, and no class file could be
found for that class, the compiler would look first for <source
root>/foo/bar.pj.
The source root defaults to the current working directory.
-c <classfile dest>
Specify the root destination for all Java class files. Class
files
are placed in subdirectories of this directory, corresponding to
their packages. For example, if a source file defines a class named
bar in a package named foo, the
generated file will be placed in
<classfile dest>/foo/bar.class.
The classfile destination root defaults to <source
root>/classes.
-t <translation dest>
Specify the root destination for all intermediate Java code. As the
compiler translates PolyJ source into Java files, it places the Java
code in a subdirectory of <translation dest>,
corresponding to
their packages. For example, if a source file defines a class named
bar in a package named foo,
the translated file will be placed in
<classfile dest>/foo/bar.java.
The translation destination root defaults to <source
root>/translated.
-I <instantiation package>
As the PolyJ compiler translates PolyJ into standard Java, it
generates an "instantiation class" for every fully instantiated
parameterized type. In order to avoid namespace conflicts, and to
avoid complicating the class-loader's security, these classes are all
placed in a separate "instantiation package". For example, if the
specified instantiation package is
myPackage.Instantiations, then
PolyJ will place its instantiation classes in
myPackage.Instantiations.
The instantiation package defaults to pjIns.
-classpath <classpath>
Specifies a colon-separated class path for PolyJ to search for class
files. For example, if this switch receives the classpath
~/myClasses:/usr/share/classes, and the compiler
finds a reference
to a class foo.bar, then it will search for that class
in the following locations, in order:
-
<classfile dest>/foo/bar.class
-
~/myClasses/foo/bar.class
-
/usr/share/classes/foo/bar.class
-
<source root>/foo/bar.pj
-sync
Requests that, in addition to compiling the files specified on the
command line, the compiler also regenerates all out-of-date
instantiation classes.
-force
Ordinarily, the compiler does not generate instantiation classes
which are not out-of-date. The "-force" option specifies that the
compiler should always generate instantiation classes, whether they
are out-of-date or not.
-g
Specifies that the compiler should pass the "-g", or "debug" switch
to the Java compiler.
-O
Specifies that the compiler should pass the "-O", or "optimize"
switch to the Java compiler.
-v
Specifies that the compiler should provide a verbose description of
the operations it performs.
POLYJROOT
Specifies the source root. This environmental variable is overridden
by the "-r" option.
POLYJCLASSTARGET
Specifies where generated ".class" files should be placed. This
environment variable is overridden by the "-c" option.
POLYJJAVATARGET
Specifies where generated ".java" files should be placed. This
environment variable is overridden by the "-t" option.
CLASSPATH
Specifies a colon-separated list of directories to search for class
files. This environment variable is overridden by the "-classpath"
option.
JAVACOMPILER
Specifies the name of a Java compiler to use. Whichever compiler is
used should be compatible in its command-line options with Sun's
javac(1).
This environment variable defaults to "javac".
PJINSPACKAGE
Specifies that name of the instantiation package, into which gen
erated instantiation classes are placed. This environment variable
is overridden by the "-I" option.
The current implementation also lacks several elements of Java 1.1;
see the full documentation for details. In particular, inner classes
are not supported.
See the postscript documentation for more known deficiencies.
The PolyJ web page.
Nicholas Mathewson, Andrew C. Myers, Barbara Liskov
The PolyJ compiler is based largely on release 0.3.1 of David
Engberg's guavac compiler. See guavac/THANKS for contributors to
guavac. See guavac/RELEASE for a list of distribution sites.