polyj - compiler for Java with parametric polymorphism


Synopsis

polyj [-r <source root>] [-c <classfile dest>] [-t <translation dest>] [-I <instantiation package>] [-classpath <classpath>] [-sync] [-force] [-gOvV] <source file> ...

Table of Contents


Description

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.

Options

-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:

-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.

Environment

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.

Bugs

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.

See also

The PolyJ web page.

Authors

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.