Type Annotations (JSR 308) Prototype Implementation README

Version 0.9.1 (19 May 2009)

For the latest version, see the Type Annotations (JSR 308) webpage.

Contents:

• Introduction
• Features of the Type Annotations compiler
  • Writing annotations in comments for forward compatibility
  • Differences from the Type Annotations (JSR 308) proposal
• Installing the Type Annotations compiler (“langtools”)
  • Installing from binary
  • Installing from source
• Differences from the OpenJDK distribution
  • Determining a diff against the OpenJDK distribution
• Contributing
  • How to report bugs
  • Credits and changelog

Introduction

(If you are impatient, you can skip to the installation instructions.)

The Type Annotations compiler is a version of the OpenJDK Java 7 “langtools” that supports the Type Annotations (JSR 308) syntax. This syntax is a backward-compatible extension of the Java language that permits annotations to appear on types.

You may use the Type Annotations compiler as a replacement for the OpenJDK javac compiler or any other Java compiler.

The Type Annotations syntax and compiler make it possible to create compiler plug-ins that check user-defined type qualifiers. The Checkers Framework makes such plug-ins easy to create, and it includes several example type qualifiers that you can start using right away.

The “Installing the Type Annotations compiler” section below contains instructions for installing, running, and testing the compiler.

IDEs such as Eclipse have not yet been updated to support the Type Annotations syntax. To use the Type Annotations compiler with Eclipse, write an Ant buildfile that compiles your project (using the Type Annotations compiler), then build by running Ant. Problem markers will show up in the Eclipse IDE as normal. (You will lose a few Eclipse features, such as error checking as you type, until Eclipse's internal compiler is updated for to support type annotations.)

Features of the Type Annotations compiler

The Type Annotations compiler that supports the JSR 308 specification (PDF, HTML), which permits annotations to appear on any occurrence of a type.

Writing annotations in comments for forward compatibility

A version of the Type Annotations compiler (that is distributed by researchers at MIT and the University of Washington) allows annotations to be written in “/* */“ (C-style) comments, for example:

  List</*@NonNull*/ String> strings;

There must be no whitespace within the comment. The compiler parses these annotations when the command-line option "-XDTAannotationsincomments" is present. For additional information about this feature, see the Checker Framework Manual.

This mechanism allows developers to use type annotations while maintaining the ability to compile their code with an unmodified Java compiler, including compilers for earlier versions of the Java language (such as Java 4, Java 5, or Java 6).

The Java 7 language will not require compilers to support this temporary mechanism, and Sun's javac compiler will not do so.

Differences from the Type Annotations (JSR 308) proposal

The Type Annotations compiler is a feature-complete implementation of the Type Annotations (JSR 308) proposal. There are no unknown differences or bugs at this point. If you find any, please help us by reporting them.

Installing the Type Annotations compiler (“langtools”)

The easiest way to install the Type Annotations compiler, which is sufficient for most users, is to install the Checker Framework binary distribution.

The remainder of this section gives instructions for installing the Type Annotations compiler from source.

Note that while these instructions install the Type Annotations compiler, you do not have to make it your default compiler. For example, you could use the Type Annotations compiler only for running pluggable type-checkers. Also, you can use javac's -target argument to generate bytecodes that are compatible with earlier JVMs, so that you can work seamlessly with colleagues who are using an earlier version of Java.

If you use an Apple Macintosh (Mac OS X) computer, you must build the compiler from source.

Installing from binary

Requirements: These instructions assume that Ant is installed. If you use an Apple Macintosh computer, you must build the compiler from source.

1. Install a new copy of OpenJDK. This new installation will be modified later (but no other copy of OpenJDK will be modified). You can put the new installation anywhere you want; a common place is in a new directory ~/jsr308. We will call that directory $JSR308.
   1. Download a JDK 7 binary snapshot: self-extracting JDK file (choose JDK, not JRE or DEBUG, and choose a binary, not a source distribution).
   2. Follow the installation instructions — essentially, just run the .exe, .sh, or .bin file that you downloaded and follow the directions.
   3. Optionally set the default version of Java. (At any time, you can run either the default or the non-default version of Java.)
      • For Linux: After installing, your old version of Java remains the default. If you wish to make OpenJDK Java 7 the default, then set your JAVA_HOME environment variable to the top-level directory of the JDK 7 installation /path/to/jdk1.7.0, and augment your PATH with /path/to/jdk1.7.0/bin. Example:

        export JSR308=$HOME/jsr308
        export JAVA_HOME=$JSR308/jdk1.7.0
        export PATH=$JAVA_HOME/bin:$PATH
        

        The shell uses the PATH variable to locate java, while Ant uses JAVA_HOME.
      • For Windows: After installing, the OpenJDK Java 7 (at c:\Program Files\Java\jdk1.7.0\) becomes the default. If you wish to retain an older version of Java as the default, then do the following:
        1. Install Java 7
        2. Copy the jdk1.7.0 and jre1.7.0 directories from Program Files\Java\ to the desktop
        3. Uninstall Java 7
        4. Move the jdk/jre directories back to Program Files\Java\
        If you want to be able to run javac from Cygwin, then set environment variables as for Linux, above.
   4. Verify that your installation is correct: run javac -version, and the output should be javac 1.7.0-ea.
2. Download the Type Annotations compiler, and unpack it to create a langtools directory. Do not do this inside the JDK 7 installation (directory jdk1.7.0) that you downloaded in the preceding step. Example commands:

   cd ~/jsr308
   wget http://groups.csail.mit.edu/pag/jsr308/current/jsr308-langtools.zip
   unzip jsr308-langtools.zip
   

3. Ensure that the JAVA_HOME environment variable points to the JDK you wish to patch, then patch your JDK 7 installation by running:

   cd langtools/binary
   ant install

   This step makes a backup copy of tools.jar and then modifies the original by copying some new .class files into it.

   (You shouldn't need to undo this step, but you can do so by running ant uninstall which puts back the original version of the tools.jar file.)

   If you get this error message:

     c:\jsr308\langtools\binary\build.xml:29: Unable to rename old file (c:\Program Files\Java\jdk1.7.0\lib\tools.jar.patched) to new file (c:\Program Files\Java\jdk1.7.0\lib\tools.jar)
   

   then rename the file manually using the shell. (This error occurs under Windows when some other process, such as an anti-virus program or another Java process, is accessing the given file.)

4. Run

   javac -version
   

   and confirm that the output contains the string jsr308, such as javac 1.7.0-jsr308-0.6.2.
   If the output is does not contain jsr308 (e.g., javac 1.7.0-ea), but you are using the correct javac binary (in langtools/dist/bin), then it is possible that tools.jar is on your classpath. You should either remove tools.jar from your classpath, or else put langtools/dist/lib/javac.jar and/or langtools/dist/lib/javap.jar on your classpath before tools.jar.

When updating to a newer version of the Type Annotations compiler, you only have to follow steps 2, 3, and 4. In other words, you only have to redo step 1 if you want a newer version of OpenJDK.

Installing from source

To build the Type Annotations compiler from source, replace step 3 from above by the following. Building from source is useful mainly for people who are developing compiler plug-ins or modifying the compiler itself. If you only want to use the compiler and plug-ins, it is sufficient to install the pre-compiled version.

Requirements: These instructions assume that Ant (version 1.7 or later) and JDK 6 are installed. You will use JDK 6 to compile OpenJDK, but will not use it thereafter. You can get JDK 6 from Sun or elsewhere. If you use an Apple Macintosh (Mac OS X), then depending on your hardware and operating system, you can either use Apple's implementation or SoyLatte.

1. Set JAVA_HOME environment file to the location of your JDK 6 or 7 installation. Most likely it is already set for Ant to work.
2. Compile the Type Annotations javac compiler and the javap tool, from directory langtools/make:

   cd langtools/make
   ant clean build-javac build-javap

3. Add the langtools/dist/bin directory to the front of your PATH environment variable.

The effect of the above commands is that the javac command invokes the Type Annotations Java compiler and the javap command invokes the Type Annotations javap, but the Java 7 OpenJDK is used for everything else.

Differences from the OpenJDK distribution

The Type Annotations distribution includes only the langtools portion of the OpenJDK distribution. The Type Annotations prototype implementation makes no modifications in other parts of the OpenJDK distribution, and the remaining parts of the distribution are not necessary to build and use the Type Annotations tools.

This Type Annotations distribution differs from the langtools portion of Sun's OpenJDK distribution in the following ways:

• The compiler (which is located in langtools/src/share/classes) supports the Type Annotations syntax; it permits annotations to appear on any occurrence of a type, not just on declarations as the original Java 5 annotations (also known as JSR 175 annotations) did.
• Note that the -proc:only command-line argument causes javac to stop after ordinary (non-type) annotation processing. Use of the -proc:only command-line argument causes type processing to be skipped.
• javac has the ability to warn about redundant casts (when directed to do so using a lint option). If the target type of the cast contains an annotation, then javac never issues a redundant cast warning, but leaves that up to the annotation processor. The processor should issue a warning exactly if the cast is redundant with respect to the entire annotated type: that is, the unannotated type parts are redundant when igoring the annotations, and the annotations are also redundant. (A potential problem is that if a type has multiple annotations that are handled by different type processors, then no redundant cast warning will ever be issued.
• This documentation file has been included.

A slightly modified version distributed by researchers at MIT and the University of Washington has some further differences:

• The compiler parses annotations written in specifically-formatted comments, which enables your code to
  • compile with earlier compilers, and
  • be type-checked by the Type Annotations compiler.

Determining a diff against the OpenJDK distribution

The Type Annotations distribution is a modification of the langtools portion of Sun's OpenJDK javac distribution.

The following commands determine the differences between the Type Annotations compiler and the OpenJDK compiler.

1. If you do not have a clean checkout of the Type Annotations compiler source, obtain one:

   
     hg clone http://hg.openjdk.java.net/type-annotations/type-annotations/langtools
     

   If you already have one, then just pull all the changes, by running the following command in the directory containing the Type Annotations compiler source

   
     hg pull; hg up
     

2. Determine the identifier of the last changeset done by Sun. Run "hg log | less" to find the last changeset with an author other than mali or mernst. The changeset identifier would be in format of:

   
     450:143956db282e
     

3. Use hg diff to generate the diff.

   
       hg diff -r450:tip
     

Contributing

We welcome bug fixes, new features, type-checking plug-ins, and other improvements. All contributions to javac (annotation-related or not) should follow the guidelines for contributing to javac. Any code contributed to javac or to the Type Annotations compiler is contributed to Sun under Sun's Contributor Agreement (SCA).

How to report bugs

If you have any problems with the compiler, please let us know; we welcome bug reports and suggestions. We will fix all reported bugs in the Type Annotations compiler. Examples of bugs include:

• Any inconsistency between the Type Annotations compiler and the JSR 308 design (PDF, HTML).
• Any annotation-related problem.
• Any problem that occurs with the Type Annotations compiler but does not occur with the OpenJDK Java 7 compiler on which the Type Annotations compiler is built.

The Type Annotations compiler is built on Sun's OpenJDK compiler. If you find a bug in the Type Annotations compiler, it might be due to a bug in the OpenJDK compiler (in which case it should be reported to Sun), or it might be due to the JSR 308 modifications (in which case it should be reported to the JSR 308 compiler implementers). In some cases (such as a problem with processing annotations on types), the responsibility is clearly with the JSR 308 modifications. Otherwise, please determine who is responsible for the bug using this procedure:

1. Obtain a copy of Mercurial reversion 59 of the OpenJDK compiler, using the commands in the diff section of this document.
2. Try your test case using the OpenJDK compiler. If the problem is present, then search the bug database (use the “Java” category). If the problem is not in the bug database, then report your bug to Sun, using category “Java” and subcategory “compiler”.

If the problem is present in the Type Annotations compiler, but not in the OpenJDK compiler, then please report it to us. Send your bug report to jsr308-bugs@lists.csail.mit.edu. This is not a mailing list for general support or questions.

Please ensure that your bug report is clear and that it is complete. Otherwise, we may be unable to understand it or to reproduce it, either of which would prevent us from fixing the bug. Sun has a description of how to write a helpful bug report. Here are some crucial points:

• Indicate exactly what you did. Show the exact commands (don't merely describe them in words). Don't skip any steps.
• Include all files that are necessary to reproduce the problem. This includes every file that is used by any of the commands you reported, and possibly other files as well.
• Indicate exactly what the result was (don't merely describe it in words). Also indicate what you expected the result to be — remember, a bug is a difference between desired and actual outcomes.
• Indicate which version of the Type Annotations compiler you are using. You can determine that by running javac -version.

Credits and changelog

The Type Annotations compiler was implemented by Matthew M. Papi and Mahmood Ali as a modification of the Sun OpenJDK compiler. See above for how to report bugs.

Differences from previous versions may be found in the changelog.

JSR 308 webpage