README

Open JDK™ Java programming language compiler (javac)
Version 1.7.0-ea

May 2007

 

Table of Contents

Introduction

This bundle contains the source code for javac, a compiler for the Java™ programming language. Build files are provided for use with NetBeans and Apache Ant. The bundle also contains a set of compiler tests, for use with the jtreg test harness.

This bundle is provided as part of the Open JDK sources. The sources for a standalone distribution of this compiler are available separately.

Files and Directories

When you install the compiler bundle, a directory named compiler will be created, containing the following:
NameDescription
README.html This file.
nbproject/project.xml A NetBeans project file.
install-dir/src/share/classes The source files for entire JDK are under that folder. Those compiler are in javax/annotation/processing, javax/lang/model, javax/tools, com/sun/source, and com/sun/tools/javac.
build.xml A build file for building the compiler, suitable for use with NetBeans and Apache Ant.
build.properties Build properties, used by build.xml.

As with the standalone compiler, tests are provided, but in this instance they are installed alongside tests for the rest of the JDK.

Specifications

The compiler is a program for compiling source code written in the Java programming language into class files suitable for execution on a Java virtual machine. It also provides API for annotation processing, and invoking the compiler programmatically.

These behaviors are governed by the following specifications:

For more details on these specifications, see the javac Guide.

These specifications are controlled by the Java Community Process (JCP.) All implementations of these specifications must pass the appropriate test suites.

Building the compiler

System Requirements

javac is written in the Java programming language. As a general rule, it can normally be compiled using tools in the latest released version of the JDK. (That is, a development version of javac version 7 can be built with JDK version 6, etc.) To bootstrap the compiler, you should also have a copy of the target JDK.

You can build javac using NetBeans or Apache Ant.

To run the compiler tests, you will need the jtreg test harness.

Bootstrapping the compiler

The source for the compiler is such that it can be compiled using the latest publicly released version of the JDK. In practice, it is typically desirable to compile it first using the latest publicly released version of the JDK, and then again using itself, and the target platform on which it will be run. This not only provides a good initial test of the newly built compiler, it also means the compiler is built with the latest compiler sources, against the target libraries.

Building with NetBeans

The installation directory for the compiler is set up as a freeform NetBeans project, so to build the compiler using NetBeans, you just have to open the project and build it in the normal way, for example, by using the operations on the Build menu.

To run the tests, you will have to set jtreg.home in one of the build.properties files, to specify where you have installed the jtreg harness. See README for more information. You might want to use a different version of the JDK when running the tests: to change that edit the build.properties in this directory and change jtreg.vm.options appropriately.

Building with Apache Ant

To build the compiler, go to the directory containing the compiler NetBeans project, and run "ant".

        % cd netbeans-compiler-dir
        % ant       
        

To run the tests, you will have to edit properties in one of the build.properties files as described in README to specify where you have installed the jtreg harness and, possibly, a different version of JDK to use when running the tests. Then, you can run the tests using the "jtreg" target.

What gets built?

Whichever build tool you use, the results are put in the dist subdirectory of your Open JDK installation directory. The following files will be built.
NameDescription
dist/lib/javac.jar This is an executable jar file containing the compiler.
dist/bin/javac This is a simple shell script to invoke the compiler.

Notes

Property files: It is possible to compile the resource property files into equivalent class files, for a minor performance improvement. For simplicity, that feature is not included here.

The launcher: JDK uses a program informally called "the launcher" which is used as a wrapper for all JDK tools, including java, javac, javadoc, and so on. The program is a deployed as a platform-dependent binary, thus obviating the need for a shell script to invoke the tools. Again for simplicity, and because that program is not normally considered part of javac, that program is not included here.

Running the compiler

Once you have built the compiler, you can run it in a number of ways.

Testing the compiler with jtreg

The Open JDK distribution contains a large test suite of unit and regression tests used to test javac. They are part of the JDK Regression Test Suite, which uses the jtreg test harness. This harness is designed to run both API-style tests, and command-line tests, such as found in the tests for javac.

The simplest way to run the tests is from NetBeans, via the normal NetBeans user interface. You can also run the tests from the command line using ant:

        % ant jtreg
        
Note:Some of the tests, written as shell tests, do not yet support this mode of operation, and the ant script is written to use -noshell to disable these tests for the time being. This restriction will be lifted in the near future.

Note:Four additional tests are ignored, using the jtreg @ignore tag, because of problems caused by bugs that have not yet been addressed.

Depending on the verbose options used, some amount of detail of the result of each test is written to the console. In addition, an HTML report about the entire test run is written to a report directory, and a results file is written for each test, in a "work" directory. That directory is

        install-dir/build/platform-arch/jtreg/compiler
        

More information on jtreg is available here.